paperless-mcp (Cloudflare Workers)

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)

Related MCP server: Paperless-NGX MCP Server

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.