PaperlessMCP

PaperlessMCP

Stop manually organizing your documents. Let AI do it.

[](https://ci.barrywalker.io/repos/3) [](https://github.com/barryw/PaperlessMCP/releases/latest) [](LICENSE)

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:

| You Say | AI Does | |---------|---------| | "Find receipts from Amazon over $100" | Searches documents with filters | | "Tag all 2024 invoices as 'Tax Year 2024'" | Bulk updates dozens of docs at once | | "Upload this PDF and file it appropriately" | Uploads, auto-tags, sets correspondent | | "Delete all documents tagged 'Junk'" | Removes with confirmation (dry-run by default) | | "Create a tag for medical records, make it red" | Creates tag with color | | "Who sends me the most documents?" | Lists correspondents by document count | | "Set up a storage path for legal documents" | Creates organized folder structure |

43 tools covering:

• 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.

---

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; 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.

---

Getting Started

You'll Need

1. A Paperless-ngx instance with an API token

(Settings → Django Admin → Tokens → Create one for your user)

1. 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.

[](https://github.com/barryw/PaperlessMCP/releases/latest)

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. The release pipeline also publishes latest, but pinning a versioned tag gives you a reproducible deployment.

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

Option 2: Claude Desktop

Add to your config file:

| OS | Path | |----|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

{
  "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 Streamable HTTP server
claude mcp add --transport http 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: LiteLLM Proxy

LiteLLM can register PaperlessMCP as a Streamable HTTP MCP server in config.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 as paperless-mcp. If LiteLLM runs directly on the host and PaperlessMCP publishes port 5000, use http://127.0.0.1:5000/mcp.

Set transport: "http" explicitly for PaperlessMCP's /mcp endpoint. LiteLLM's MCP config defaults to sse, which is the wrong transport for this endpoint.

PAPERLESS_API_TOKEN belongs on the PaperlessMCP service; it is the token PaperlessMCP uses when calling Paperless-ngx. PaperlessMCP does not require an inbound token on /mcp unless 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-level mcp_servers key.

Option 5: 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

# 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 .

[See the manifests](k8s/)

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

Option 6: From Source

For contributors and tinkerers:

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

Requires .NET 10 SDK.

---

The Full Toolbox

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

Documents — the main event

| Tool | What it does | |------|--------------| | paperless_documents_search | Find documents with full-text search and filters | | paperless_documents_get | Get a document by ID with all metadata | | paperless_documents_upload | Upload a document (base64) | | paperless_documents_upload_from_path | Upload from a file path | | paperless_documents_update | Update title, tags, correspondent, etc. | | paperless_documents_delete | Delete a document (requires confirmation) | | paperless_documents_bulk_update | Update multiple documents at once | | paperless_documents_download | Get download URL for original file | | paperless_documents_preview | Get preview URL | | paperless_documents_thumbnail | Get thumbnail URL | | paperless_documents_reprocess | Re-run OCR on a document |

Tags — organize everything

| Tool | What it does | |------|--------------| | paperless_tags_list | List all tags | | paperless_tags_get | Get a tag by ID | | paperless_tags_create | Create a tag with optional color, matching rules, and parent | | paperless_tags_update | Update a tag, including changing or clearing its parent | | paperless_tags_delete | Delete a tag | | paperless_tags_bulk_delete | Delete multiple tags |

Correspondents — who sends you stuff

| Tool | What it does | |------|--------------| | paperless_correspondents_list | List all correspondents | | paperless_correspondents_get | Get a correspondent by ID | | paperless_correspondents_create | Create with optional matching rules | | paperless_correspondents_update | Update a correspondent | | paperless_correspondents_delete | Delete a correspondent | | paperless_correspondents_bulk_delete | Delete multiple correspondents |

Document Types — invoices, receipts, contracts...

| Tool | What it does | |------|--------------| | paperless_document_types_list | List all document types | | paperless_document_types_get | Get a document type by ID | | paperless_document_types_create | Create with optional matching rules | | paperless_document_types_update | Update a document type | | paperless_document_types_delete | Delete a document type | | paperless_document_types_bulk_delete | Delete multiple document types |

Storage Paths — where things live

| Tool | What it does | |------|--------------| | paperless_storage_paths_list | List all storage paths | | paperless_storage_paths_get | Get a storage path by ID | | paperless_storage_paths_create | Create with path template | | paperless_storage_paths_update | Update a storage path | | paperless_storage_paths_delete | Delete a storage path | | paperless_storage_paths_bulk_delete | Delete multiple storage paths |

Custom Fields — your own metadata

| Tool | What it does | |------|--------------| | paperless_custom_fields_list | List all custom field definitions | | paperless_custom_fields_get | Get a custom field by ID | | paperless_custom_fields_create | Create a field (string, date, number, monetary, etc.) | | paperless_custom_fields_update | Update a field definition | | paperless_custom_fields_delete | Delete a field | | paperless_custom_fields_assign | Assign a field value to a document |

Health — is it alive?

| Tool | What it does | |------|--------------| | paperless_ping | Check connectivity and auth | | paperless_capabilities | List supported features |

---

Configuration

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

| Variable | Required | Default | Description | |----------|:--------:|---------|-------------| | PAPERLESS_BASE_URL | Yes | — | Your Paperless-ngx URL | | PAPERLESS_API_TOKEN | Yes | — | API token for authentication | | MCP_PORT | | 5000 | Port for Streamable HTTP mode | | MCP_RELAX_ACCEPT_HEADER | | false | Normalize /mcp POST Accept headers for clients that cannot send both Streamable HTTP media types | | MAX_PAGE_SIZE | | 100 | Upper bound for paginated Paperless-ngx requests made by this server | | HTTP_TIMEOUT_SECONDS | | 30 | Timeout for requests to Paperless-ngx. Raise it if large full-text searches time out |

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

LocalAI Compatibility

Streamable HTTP clients are expected to send Accept: application/json, text/event-stream on /mcp POST requests. Some clients cannot configure that header. Set MCP_RELAX_ACCEPT_HEADER=true to have PaperlessMCP normalize missing or incomplete Accept headers before the MCP SDK handles the request.

---

Support the Project

If PaperlessMCP saves you time, consider supporting development:

[](https://github.com/sponsors/barryw) [](https://ko-fi.com/barryw)

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; bulk operations default to dry-run

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full rundown.

---

License

[MIT](LICENSE) — 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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: barryw
• Source: barryw/PaperlessMCP
• License: MIT

Install and usage instructions live in the source repository linked above.