What is Paperless-NGX MCP Server?
This is the maintained fork of nloui/paperless-mcp, the original Paperless-ngx MCP server, whose last commit was on 11 November 2025. Baruch Rothkoff's fork (baruchiro/paperless-mcp) has about 149 GitHub stars against the original's 248, but it is the one still shipping: v2.2.1 came out on 11 September 2026, and its npm package had 683 downloads in the week to 29 October 2026 against 171 for the original.
It wraps the Paperless-ngx REST API with about 31 tools covering documents, notes, tags, correspondents, document types, custom fields and mail accounts and rules. It runs over stdio with npx -y @baruchiro/paperless-mcp@latest, or as a Docker image serving Streamable HTTP and SSE on port 3000. It needs the URL of your Paperless-ngx instance and an API token from your profile page. The repository is ISC-licensed.
How to install Paperless-NGX MCP Server
npx -y @baruchiro/paperless-mcp@latestIs Paperless-NGX MCP Server worth it?
For people who already keep their letters, invoices and tax papers in Paperless-ngx, this server turns the archive into something an agent can search and reorganise. query_documents passes through full-text search, more-like-this lookups and structured custom-field queries such as finding every invoice with no invoice number. That covers most of what a person does in the web interface.
The tool list goes well past reading. bulk_edit_documents can merge, split, rotate, delete pages from and delete documents, and change their permissions; post_document uploads files up to 100 MB; the mail tools create and edit the rules that decide what Paperless pulls out of your inbox. Only note and mail-rule deletion ask for an explicit confirm flag. A bulk delete does not, so the client's approval prompt is the only guard.
The fork's security work is the main reason to pick it over the original. Version 2.0.0 made HTTP mode reject requests without a Bearer token, closing an endpoint that previously fell back to the server's own key for any caller on the network. Each HTTP client now sends its own Paperless token, so Paperless permissions apply per user. Uploads by file path read any file the process can see unless PAPERLESS_MCP_UPLOAD_PATHS restricts them, and that variable is optional.
The weaker points are the usual ones for a one-maintainer community server. Paperless-ngx v3.0.0 dropped REST API versions below 9, and older configurations now see HTTP 406 errors until PAPERLESS_API_VERSION is set. The documentation is a long README rather than a docs site. Document text from scanned mail is untrusted input, so an agent reading it is exposed to prompt injection while holding write access to the archive.
Where it earns its place
A freelancer with five years of invoices and receipts in Paperless-ngx
Find every 2025 invoice still missing an invoice number before filing taxes
query_documents with a custom-field query lists the gaps and bulk_edit_documents tags them for follow-up. Free on top of an existing Paperless install; the cost is a few tool calls and reviewing each bulk edit.
A home-lab owner who scans household post into Paperless
Set up mail rules so utility bills are pulled from email and tagged automatically
The agent lists mail accounts, then calls create_mail_rule with sender and subject filters and tags to assign. Account passwords are redacted from tool output, but a wrong rule can mark or move mail in the real inbox.
A small accountancy practice self-hosting Paperless for client files
Give two staff an assistant that respects who can see which client's documents
Run the Docker image in HTTP mode and have each client send its own Paperless token as a Bearer header, so Paperless permissions apply per person. Keep the server off the public internet and leave --no-auth unset.
Before you commit
- Setup
- Add npx -y @baruchiro/paperless-mcp@latest with PAPERLESS_URL and PAPERLESS_API_KEY to the client config, or run ghcr.io/baruchiro/paperless-mcp for HTTP and SSE on port 3000. The README has a Cursor install link and a Continue example; it takes a few minutes once you have a token.
- Integrations
- About 31 tools: listing, querying, downloading and uploading documents, thumbnails, notes, tags, correspondents, document types, custom fields, and mail accounts and rules. Roughly half of them write.
- Data and privacy
- Everything the API token can reach, including delete. In HTTP mode since v2.0.0 each request must carry its own Bearer token unless --no-auth is set. File-path uploads read any local file unless PAPERLESS_MCP_UPLOAD_PATHS is set. No GitHub security advisories are published.
- Cost at scale
- Free; Paperless-ngx is self-hosted, so the only costs are your server and model tokens. Large result pages and base64 uploads are the main sources of context bloat.
- Limits
- Paperless-ngx v3.0.0 rejects API versions below 9 with HTTP 406. search_documents is deprecated in favour of query_documents. Destructive bulk methods have no confirm flag.
What’s good
- About 31 tools, including custom-field queries and mail rules
- Per-request Bearer tokens in HTTP mode since v2.0.0
- npx and Docker images; end-to-end tests run against real Paperless-ngx
- Actively maintained, unlike the original repo
What’s not
- Bulk delete, merge and split run without a confirm flag
- File-path uploads are unrestricted unless you set an allowlist
- Single maintainer; about 149 stars
- Older setups hit HTTP 406 after Paperless-ngx 3.0
Best for
Paperless-ngx users who want an agent to find, tag and file documents and will keep write calls behind approval prompts.
Paperless-NGX MCP Server alternatives
Paperless-NGX MCP Server: common questions
- Is Paperless-NGX MCP Server worth it?
- The Paperless-ngx server worth installing, broad enough to run a filing clerk's whole day, and broad enough to delete your archive if you let it. We rate it 3.8 out of 5.
- How much does Paperless-NGX MCP Server cost?
- Free and open source (ISC). Paperless-ngx itself is free and self-hosted.
- What are the downsides of Paperless-NGX MCP Server?
- Bulk delete, merge and split run without a confirm flag; file-path uploads are unrestricted unless you set an allowlist; single maintainer; about 149 stars; older setups hit HTTP 406 after Paperless-ngx 3.0.
- Who is Paperless-NGX MCP Server best for?
- Paperless-ngx users who want an agent to find, tag and file documents and will keep write calls behind approval prompts.
- How much does Paperless-NGX MCP Server cost for a team or in production?
- Free; Paperless-ngx is self-hosted, so the only costs are your server and model tokens. Large result pages and base64 uploads are the main sources of context bloat.
- Is Paperless-NGX MCP Server safe for company data?
- Everything the API token can reach, including delete. In HTTP mode since v2.0.0 each request must carry its own Bearer token unless --no-auth is set. File-path uploads read any local file unless PAPERLESS_MCP_UPLOAD_PATHS is set. No GitHub security advisories are published.
- What are the best Paperless-NGX MCP Server alternatives?
- The closest alternatives we have reviewed are Filesystem (reference server), MarkItDown MCP and Zotero MCP.
Answers checked Oct 31, 2026.