# Paperless-ngx

Wires your Paperless-ngx archive into an AI assistant, so you can search, tag, upload and edit documents from the chat.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 11
- Author: cubinet-code
- License: ISC · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cubinet-code/paperless-ngx-mcp
- Updated: 2026-09-30
- HTML: https://affpapa.org/en/nevibecode/mcp/paperless-ngx

## What it does

The server hands the assistant the Paperless-NGX REST API. From there it can look up documents, manage tags and correspondents, define document types and custom fields, and reach workflows, mail rules, versions, notes and the trash.

Destructive calls ask first. Every `delete_*` tool, plus `empty_trash`, `merge_documents_as_versions` and bulk delete, needs `confirm: true`. Bulk edits over all matching documents reject filters that Paperless would quietly drop. The `triage_inbox` prompt drafts its changes and waits for your approval before writing anything.

Two settings are mandatory: `PAPERLESS_URL` and `PAPERLESS_API_KEY`. You generate the token from your own profile page inside Paperless. This build targets Paperless-ngx 3.2; on the 2.x line use `paperless-ngx-mcp@3.1.1` instead. Run it with `npx`, or pick the Docker image or the Claude Desktop extension.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `PAPERLESS_URL`, `PAPERLESS_API_KEY`, `PAPERLESS_PUBLIC_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env PAPERLESS_URL=<PAPERLESS_URL> --env PAPERLESS_API_KEY=<PAPERLESS_API_KEY> --env PAPERLESS_PUBLIC_URL=<PAPERLESS_PUBLIC_URL> --transport stdio paperless-ngx -- npx -y paperless-ngx-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add paperless-ngx --env PAPERLESS_URL=<PAPERLESS_URL> --env PAPERLESS_API_KEY=<PAPERLESS_API_KEY> --env PAPERLESS_PUBLIC_URL=<PAPERLESS_PUBLIC_URL> -- npx -y paperless-ngx-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "paperless-ngx": {
            "command": "npx",
            "args": [
                "-y",
                "paperless-ngx-mcp"
            ],
            "env": {
                "PAPERLESS_URL": "<PAPERLESS_URL>",
                "PAPERLESS_API_KEY": "<PAPERLESS_API_KEY>",
                "PAPERLESS_PUBLIC_URL": "<PAPERLESS_PUBLIC_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "paperless-ngx": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "paperless-ngx-mcp"
            ],
            "env": {
                "PAPERLESS_URL": "<PAPERLESS_URL>",
                "PAPERLESS_API_KEY": "<PAPERLESS_API_KEY>",
                "PAPERLESS_PUBLIC_URL": "<PAPERLESS_PUBLIC_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e PAPERLESS_URL=<PAPERLESS_URL> -e PAPERLESS_API_KEY=<PAPERLESS_API_KEY> -e PAPERLESS_PUBLIC_URL=<PAPERLESS_PUBLIC_URL> paperless-ngx npx -y paperless-ngx-mcp
```
Replace <…> with your own values

## When to use it
- pull up every document carrying a given tag
- search inside document text for a phrase
- create a tag with a set colour and apply it in bulk
- reassign documents from one correspondent to another
- strip a PDF password and keep the unlocked copy as a version

## Example prompts
- List every document tagged 'Invoice'
- Find documents that mention 'tax return'
- Create a tag named 'Receipts' with colour #FF0000

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md