PaperlessMCP

Stop manually organizing your documents. Let AI do it.

You've got a Paperless-ngx instance. You've got hundreds (thousands?) of documents. You know you 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 designed specifically for AI to manage your documents while you do literally anything else.

What Can AI Do With Your Paperless?

Everything. Full CRUD on every entity type:

43 tools covering:

• Documents — search, upload, download, update, delete, bulk operations, OCR reprocessing
• Tags — full CRUD with colors and matching rules
• 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 and default to dry-run mode. AI can't nuke your archive by accident.

Is PaperlessMCP Right For You?

Yes, if:

• 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

No, if:

• 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, but you can dry-run everything first)

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

Getting Started

You'll Need

1. A Paperless-ngx instance with an API token (Settings → Django Admin → Tokens → Create one for your user)

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

Option 1: Docker (Recommended)

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 \
  ghcr.io/barryw/paperlessmcp:vX.Y.Z

Grab the version from the badge above. We don't use latest because you deserve reproducible deployments.

Connect your MCP client to http://localhost:5000/mcp and start talking to your documents.

Option 2: Claude Desktop

Add to your config file:

{
  "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.

Option 3: Claude Code

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

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

Or run from source with stdio:

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

Verify it's there:

claude mcp list

Option 4: Kubernetes

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

# Create your secrets
kubectl create secret generic paperless-mcp \
  --from-literal=PAPERLESS_BASE_URL=https://your-paperless.example.com

kubectl create secret generic paperless-token \
  --from-literal=token=your-api-token-here

# Deploy (edit the image tag first)
kubectl apply -k .

See the manifests

Includes: Deployment, Service, Ingress, Kustomization. Tweak to taste.

Option 5: From Source

For contributors and tinkerers:

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

Requires .NET 10 SDK.

The Full Toolbox

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

Configuration

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

Aliases supported: PAPERLESS_URL and PAPERLESS_TOKEN also work if that's your style.

Support the Project

If PaperlessMCP saves you time, consider supporting development:

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

Contributing

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

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

The rules:

• Conventional commits (feat:, fix:, docs:, etc.) — versions bump automatically
• Tests pass or it doesn't merge
• Destructive operations need confirm=true and dry-run by default

See CONTRIBUTING.md for the full rundown.

License

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

Acknowledgments

• 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