Paperless-ngx

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, share_link_bundles, the split PDF operations) that this server assumes exist.

Quick start

npx -y mcp-paperless-ngx --check   # verify connectivity, then exit

Claude Code

claude mcp add paperless --scope user \

--env PAPERLESS_URL=https://paperless.example.com \ --env PAPERLESS_TOKEN=your-api-token \ -- npx -y mcp-paperless-ngx

Claude Desktop, Cursor, Cline, and other MCP clients

{

"mcpServers": { "paperless": { "command": "npx", "args": ["-y", "mcp-paperless-ngx"], "env": { "PAPERLESS_URL": "https://paperless.example.com", "PAPERLESS_TOKEN": "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

CLI flags --url, --token, --public-url, --toolsets and --read-only override the environment. --check verifies connectivity, --list-tools prints the enabled tools.

Toolsets

mail and admin are off by default because most sessions never need them and every extra tool costs context on every request. Enable them explicitly:

PAPERLESS_TOOLSETS=documents,metadata,system,mail

PAPERLESS_TOOLSETS=all

Context cost

Wrapping an API for a language model has a cost the API itself does not: everything the model sees is paid for on every request. Two places where that bites, and what this server does about them.

Responses. Three shapes are expensive in Paperless and easy to return by accident:

Tool definitions. These are the larger and less obvious cost: names, descriptions and JSON schemas ship with *every* request, whether or not any tool is called.

There is no way to make that free — it is the price of a tool the model can use without guessing. But it is worth being deliberate: if your sessions only ever search and file documents, running PAPERLESS_TOOLSETS=documents,metadata saves more context than any response-trimming does.

Safety

The server exposes destructive operations, because a document manager without them is not much of a manager. It does not try to guess when they are appropriate — that judgment belongs to the client and the user. What it does instead:

• Destructive tools are annotated destructiveHint: true, so MCP clients can require confirmation.
• Tool descriptions state plainly what cannot be undone (empty_trash, delete_custom_field, delete_originals) and ask for confirmation before the call.
• --read-only removes every write tool from the list, rather than refusing them at call time.
• Bulk endpoints support an "apply to everything matching this filter" mode. This server does not expose it: bulk tools take explicit ID lists, so a wrong filter cannot silently affect the entire archive.
• create_share_link produces a publicly reachable URL. Its description says so, and the audit_sharing prompt exists to review what is already exposed.

Credential-adjacent endpoints (token generation, TOTP enrolment, disabling someone's second factor) are deliberately not exposed. See EXCLUDED_ENDPOINTS for the full list and the reasoning.

Prompts

Registered as slash commands in clients that support MCP prompts:

Testing

Three layers, because they catch different things:

npm test                                        # logic — no network

PAPERLESS_URL=… PAPERLESS_TOKEN=… \ node scripts/smoke-test.mjs # all 55 read-only tools, live PAPERLESS_URL=… PAPERLESS_TOKEN=… \ node scripts/write-test.mjs # writes, live — see the warning

npm test checks this server's own reasoning: endpoint coverage, enum values against the schema, that no list tool leaks raw API objects, that read-only mode really removes writes.

smoke-test.mjs checks the assumptions it makes about Paperless. It calls every read-only tool against a real instance, resolving IDs from list calls instead of hard-coding them, and prints response sizes so expensive tools stay visible. It writes nothing.

write-test.mjs covers the rest: upload and consumption, updating every field type, notes, bulk tag edits, share links, rotation, and a trash round trip.

It only touches objects it creates itself. Everything it makes is named

with a zz-mcp-test prefix and deleted again at the end, and it never modifies

a document it did not upload. If a run is interrupted, leftovers with that

prefix are safe to delete. Prefer a test instance if you have one.

Keeping up with Paperless

PAPERLESS_URL=… PAPERLESS_TOKEN=… node scripts/sync-schema.mjs

npm test

sync-schema.mjs regenerates schema/endpoints.json from your own instance's OpenAPI document. The test suite then reports any endpoint that is neither exposed nor explicitly excluded. That is the whole maintenance loop: point it at a newer Paperless and the test tells you what changed.

Development

npm install

npm start # run from source npm run build # compile to build/ npm test # unit tests + coverage checks npm run inspect # build, then open the MCP inspector

Prior art

Several MCP servers for Paperless-ngx exist, and the two most active both work against 3.x: cubinet-code/paperless-ngx-mcp adapts between 2.x and 3.x automatically, and baruchiro/paperless-mcp lets you choose the API version (PAPERLESS_API_VERSION, default 9). If you need to support both majors from one install, use one of those.

This server takes the opposite trade: it assumes API version 10 and nothing older. That is what lets it reach the endpoints 3.x introduced — nested tags, document versions, share_link_bundles, the standalone PDF operations — and lets a test assert that all 92 documented endpoints are accounted for. It also trims list responses server-side via ?fields=, so OCR text does not ride along by default.

License

MIT. See LICENSE.

Built by eichner.cloud — self-hosted, and rather attached to it.