paperless-mcp (Cloudflare Workers)

IMPORTANT

This is 100% vibecode, but it works! The deploy guide at./DEPLOY.md is reliable as of July 2026

paperless-mcp

A remote MCP server for paperless-ngx, deployed on Cloudflare Workers so it can be registered behind a Cloudflare MCP server portal and used from claude.ai (web) and other hosted MCP clients — no local process required.

Ported from nloui/paperless-mcp (stdio/Express) to Cloudflare's McpAgent + Streamable HTTP stack (Web-standard APIs only — no Express).

Tools (16, exact parity with the reference)

Area	Tools
Documents	`search_documents`, `get_document`, `download_document`, `post_document`, `bulk_edit_documents`
Tags	`list_tags`, `create_tag`, `update_tag`, `delete_tag`, `bulk_edit_tags`
Correspondents	`list_correspondents`, `create_correspondent`, `bulk_edit_correspondents`
Document types	`list_document_types`, `create_document_type`, `bulk_edit_document_types`

Architecture

claude.ai / web agent  ──OAuth (Cloudflare Access, your IdP)──▶  MCP Server Portal
                                                                      │
                                          Streamable HTTP + static header (admin credential)
                                                                      ▼
                              paperless-mcp Worker  (McpAgent.serve("/mcp"))
                                                                      │
                                       Token auth (Authorization: Token <API_KEY>)
                                                                      ▼
                                          your paperless-ngx instance /api

This deployment is single-tenant: one Worker talks to one paperless-ngx instance, using credentials stored as Worker secrets. The Worker itself is protected by a single static bearer token (MCP_AUTH_TOKEN) checked on every request — the portal (or any other client) must send Authorization: Bearer <MCP_AUTH_TOKEN>.

1. Prerequisites

A paperless-ngx instance reachable over public HTTPS (a direct hostname, or a Cloudflare Tunnel). Workers run on Cloudflare's edge and cannot reach a LAN-only instance directly.
A paperless-ngx API token: log in → user icon → My Profile → generate/copy the API token.
Node.js + npm, and a Cloudflare account.

2. Install and deploy

Follow the DEPLOY.md instructions.

4. Local development

cp .dev.vars.example .dev.vars   # fill in real values (gitignored)
npm run dev                       # wrangler dev on http://localhost:8787
npm run type-check                # tsc --noEmit

Test with MCP Inspector:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL: http://localhost:8787/mcp
# Header: Authorization: Bearer <MCP_AUTH_TOKEN>

A request with a missing or wrong Authorization header returns 401 Unauthorized; the tools list should show all 16 tools with the correct token.

Notes

nodejs_compat is enabled (see wrangler.jsonc) so Buffer works for the base64 handling in post_document / download_document.
Large uploads/downloads are bounded by Workers request/response limits — fine for typical PDFs, but very large archives may need a different approach.
search_documents strips the OCR content field and thumbnail/download URLs from results (as in the reference implementation) to avoid blowing up token usage; use get_document for full detail on a specific document.