tobee89/mcp-paperless-ngx

A Model Context Protocol server for
Paperless-ngx 3.x
Full REST API coverage, schema-aware, token-frugal.
Built against REST API version 10, with three things it does differently:
Accounted coverage. Every one of the 92 documented endpoints is either exposed as a tool or
listed in src/tools/coverage.ts with a written reason for leaving it
out. A test enforces this, so a Paperless release that adds an endpoint fails CI instead of
quietly going unsupported.
Token discipline. A Paperless document carries its full OCR text. Naive wrappers return it by
default and a single search can exhaust the model's context. Here, list results are trimmed
server-side via ?fields=, the text lives behind its own paginated tool, and no list endpoint
hands the raw API response through — a test enforces that. See Context cost.
Scoped surface. 99 tools would drown a model's tool list. Toolsets let you expose only what a
given client needs, and --read-only removes every write path entirely.
Paperless-ngx 2.x is not supported: API version 10 introduced endpoints (nested tags, document
versions, sharelinkbundles, the split PDF operations) that this server assumes exist.
## Quick start
bash
npx -y mcp-paperless-ngx --check # verify connectivity, then exit
### Claude Code
bash
claude mcp add paperless --scope user \
--env PAPERLESSURL=https://paperless.example.com \
--env PAPERLESSTOKEN=your-api-token \
-- npx -y mcp-paperless-ngx
### Claude Desktop, Cursor, Cline, and other MCP clients
json
"mcpServers": {
"paperless": {
"command": "npx",
"args": ["-y", "mcp-paperless-ngx"],
"env": {
"PAPERLESSURL": "https://paperless.example.com",
"PAPERLESSTOKEN": "your-api-token"
### Getting an API token
Paperless web UI → your username (top right) → My Profile → the circular arrow button next to
the API token field.
## Configuration
| Variable | Required | Default | Purpose |
| PAPERLESSURL | yes | — | Base URL the server talks to. |
| PAPERLESSTOKEN | yes | — | API token. PAPERLESSAPIKEY also works. |
| PAPERLESSPUBLICURL | no | PAPERLESSURL | URL used when building links for the user, if the instance is reachable under a different name from outside. |
| PAPERLESSTOOLSETS | no | see below | Comma-separated toolsets, or all. |
| PAPERLESSREADONLY | no | false | Expose only tools that cannot change anything. |
| PAPERLESSHEADERS | no | — | Extra request headers, as JSON ({"X-Auth":"…"}) or Name: value, Name: value. Needed behind forward-auth proxies such as Authentik or Authelia. |
| PAPERLESSDOWNLOADDIR | no | system temp | Where downloaded files are written. |
| PAPERLESSMAXPAGESIZE | no | 100 | Hard ceiling on list page sizes, whatever the model asks for. |
| PAPERLESSTIMEOUTMS | no | 60000 | Request timeout. |
| PAPERLESSAPIVERSION | no | 10 | REST API version sent in the Accept header. |
CLI flags --url, --token, --public-url, --toolsets and --read-only override the
environment. --check verifies connectivity, --list-tools prints the enabled tools.
## Toolsets
| Toolset | Default | Contents |
| documents | on | Search, read, update, delete, upload, download, notes, bulk and PDF operations |
| metadata | on | Tags, correspondents, document types, storage paths |