PaperlessMCP

Stop manually organizing your documents. Let AI do it.

You've got a Paperless-ngx instance. You've got hundreds (thousands?) of documents. Youknowyou should tag them, set correspondents, organize them properly. But who has time for that?

PaperlessMCP connects your Paperless-ngx to any MCP-compatible AI. Now instead of clicking through the UI, you just ask:

"Find all my tax documents from 2023"

"Tag these 50 invoices as 'Business Expense' and set the correspondent to 'Acme Corp'"

"Upload this receipt and figure out what it is"

"What documents am I missing from my insurance folder?"

It's Paperless-ngx on LLM steroids. An interface designedspecificallyfor AI to manage your documents while you do literally anything else.

Everything. Full CRUD on every entity type:

- Documents— search, upload, download, update, delete, bulk operations, OCR reprocessing
- Tags— full CRUD with colors, matching rules, and hierarchical parents
- Correspondents— track who sends you stuff
- Document Types— classify invoices, receipts, contracts, whatever
- Storage Paths— organize files with smart templates
- Custom Fields— add your own metadata (dates, amounts, URLs, etc.)

All destructive operations require explicit confirmation. Bulk operations default to dry-run mode, so AI can't nuke your archive by accident.

- You run Paperless-ngx (self-hosted or cloud)
- You use any AI assistant that speaks MCP (Claude, or anything else supporting the protocol)
- You have a backlog of untagged documents and feel guilty about it
- You'd rather say "organize this" than click 47 buttons
- You want to query your documents in plain English
- You think computers should work for you, not the other way around

- You don't use Paperless-ngx (this isn't a general document tool)
- You enjoy manually tagging documents (weirdo, but respect)
- You don't trust AI with your files (fair; destructive operations require confirmation, and bulk operations default to dry-run)

The sweet spot:You've got Paperless running, you've got an MCP-compatible AI, and you want them to be friends.
-

A Paperless-ngx instancewith an API token(Settings → Django Admin → Tokens → Create one for your user)

An MCP-compatible AI(Claude Desktop, or anything speaking the protocol)

The fastest path from zero to talking to your documents.

docker run -d \ --name paperless-mcp \ --restart unless-stopped \ -e PAPERLESS_BASE_URL=https://your-paperless.example.com \ -e PAPERLESS_API_TOKEN=your-token-here \ -p 5000:5000 \ -v paperless-outbox:/home/mcp/outbox \ ghcr.io/barryw/paperlessmcp:vX.Y.Z

Grab the version from the badge above.The release pipeline also publisheslatest, but pinning a versioned tag gives you areproducible deployment.

Thepaperless-outboxvolume is wherepaperless_documents_export_to_outboxwrites exported files. Without it the exports stay inside the container and no other process can reach them — seeSharing the outbox with another MCP server.

{ "mcpServers": { "paperless": { "command": "dotnet", "args": ["run", "--project", "/path/to/PaperlessMCP/PaperlessMCP", "--", "--stdio"], "env": { "PAPERLESS_BASE_URL": "https://your-paperless.example.com", "PAPERLESS_API_TOKEN": "your-token-here" } } } }

Restart Claude Desktop. Look for the tools icon — Paperless should be there.

One command if you're already running the server somewhere:

# Connect to a running Streamable HTTP server claude mcp add --transport http paperless http://localhost:5000/mcp

claude mcp add --transport stdio paperless \ -e PAPERLESS_BASE_URL=https://your-paperless.example.com \ -e PAPERLESS_API_TOKEN=your-token-here \ -- dotnet run --project /path/to/PaperlessMCP/PaperlessMCP -- --stdio

LiteLLM can register PaperlessMCP as a Streamable HTTP MCP server inconfig.yaml.

Start PaperlessMCP first using Docker, Kubernetes, or source, then add it to LiteLLM:

mcp_servers: paperless: url: "http://paperless-mcp:5000/mcp" transport: "http" description: "Paperless-ngx document management"

Use a URL that the LiteLLM process can reach. In Docker Compose, set the host to the PaperlessMCP service name from that Compose file, such aspaperless-mcp. If LiteLLM runs directly on the host and PaperlessMCP publishes port 5000, usehttp://127.0.0.1:5000/mcp.

Settransport: "http"explicitly for PaperlessMCP's/mcpendpoint. LiteLLM's MCP config defaults tosse, which is the wrong transport for this endpoint.

PAPERLESS_API_TOKENbelongs on the PaperlessMCP service; it is the token PaperlessMCP uses when calling Paperless-ngx. PaperlessMCP does not require an inbound token on/mcpunless you put a separate auth layer, such as a reverse proxy, in front of it.

For LiteLLM database-backed MCP storage, enable database storage in LiteLLM:

general_settings: store_model_in_db: true

For static configuration, keep the server under the top-levelmcp_serverskey.

For the homelabbers running k8s. We include ready-to-use manifests with Kustomize support.

# Clone and customize git clone https://github.com/barryw/PaperlessMCP.git cd PaperlessMCP/k8s # Customize the checked-in manifests: # - Set PAPERLESS_BASE_URL in secret.yaml. # - Pin a versioned image tag in deployment.yaml. # - The image is public, so remove imagePullSecrets unless your cluster # provides the referenced ghcr-secret. # Create the API token secret (it is not managed by kustomization.yaml) kubectl create secret generic paperless-token \ --from-literal=token=your-api-token-here # Deploy kubectl apply -k .

Includes: Deployment, Service, Ingress, base-URL Secret, and Kustomization. Tweak to taste.

git clone https://github.com/barryw/PaperlessMCP.git cd PaperlessMCP dotnet run --project PaperlessMCP # Streamable HTTP on :5000 dotnet run --project PaperlessMCP -- --stdio # stdio mode

43 tools, organized by what they touch. Every entity supports full CRUD.

Environment variables. That's it. No config files to manage.

Aliases supported:PAPERLESS_URLandPAPERLESS_TOKENalso work if that's your style, andOUTBOX_DIRis accepted forPAPERLESS_OUTBOX_DIR.

Sharing the outbox with another MCP server

paperless_documents_export_to_outboxdownloads a document server-side and writes it toPAPERLESS_OUTBOX_DIR, returning{path, filename, mime_type, size_bytes}. The point is that the bytes never travel through the model's context: another tool (a mail server that attaches files by path, say) reads the file directly.

That only works if both containers see the same directory. Mount one volume into both, and make sure the path the other server is told to read matches the path it sees:

services: paperless-mcp: image: ghcr.io/barryw/paperlessmcp:vX.Y.Z environment: PAPERLESS_BASE_URL: https://your-paperless.example.com PAPERLESS_API_TOKEN: your-token-here PAPERLESS_OUTBOX_DIR: /home/mcp/outbox ports: - "5000:5000" volumes: - outbox:/home/mcp/outbox some-other-mcp: image: example/other-mcp:latest volumes: - outbox:/home/mcp/outbox volumes: outbox:

Two things to know before you rely on it:

- Names carry the document id.A derived name gets the id inserted before the extension (invoice.pdfbecomesinvoice_42.pdf), so two documents whose file has the same name cannot overwrite each other. Re-exporting the same document replaces its own file. Afilenameyou pass yourself is used as given, so repeated exports under one name do replace each other.
- The archived version is named as such.Withoriginal=false(the default) Paperless serves the archived PDF, so the export is named after the archived file rather than after a.jpgor.docxoriginal. Passoriginal=trueto get the uploaded file under its own name.
- Exports appear whole.The download is streamed to a temporary file in the outbox and renamed into place, so a reader on the other side of the volume never picks up a half-written file, and a symlink planted at the destination is replaced rather than written through.
- The directory must be writable by the container user.The image runs as root unless you override it, so exports land in a bind mount owned by root — if the consuming container runs as a non-root user, setPAPERLESS_OUTBOX_DIRto a directory both can write, or fix the ownership yourself. The directory is created on first export, and a failure surfaces there rather than at startup.

Streamable HTTP clients are expected to sendAccept: application/json, text/event-streamon/mcpPOST requests. Some clients cannot configure that header. SetMCP_RELAX_ACCEPT_HEADER=trueto have PaperlessMCP normalize missing or incompleteAcceptheaders before the MCP SDK handles the request.

If PaperlessMCP saves you time, consider supporting development:

Every bit helps keep the lights on and the commits flowing.

Yes please. We use trunk-based development with conventional commits.

git clone https://github.com/barryw/PaperlessMCP.git cd PaperlessMCP dotnet build dotnet test

- Conventional commits (feat:,fix:,docs:, etc.) — versions bump automatically
- Tests pass or it doesn't merge
- Destructive operations needconfirm=true; bulk operations default to dry-run

SeeCONTRIBUTING.mdfor the full rundown.

MIT— do whatever you want, just don't blame me.

- Paperless-ngx— the document system that makes this worth building
- Model Context Protocol— the glue between AI and everything else
- Everyone who's ever felt guilty about their untagged documents

AI-powered reading triage MCP. 26 tools with a 24h burn timer. Read less, absorb more.