Paperless-ngx — Claude Code MCP server: document access
Wires your Paperless-ngx archive into an AI assistant, so you can search, tag, upload and edit documents from the chat.
claude mcp add --env PAPERLESS_URL=<PAPERLESS_URL> --env PAPERLESS_API_KEY=<PAPERLESS_API_KEY> --env PAPERLESS_PUBLIC_URL=<PAPERLESS_PUBLIC_URL> --transport stdio paperless-ngx -- npx -y paperless-ngx-mcpWhat Paperless-ngx does
The server hands the assistant the Paperless-NGX REST API. From there it can look up documents, manage tags and correspondents, define document types and custom fields, and reach workflows, mail rules, versions, notes and the trash.
Destructive calls ask first. Every delete_* tool, plus empty_trash, merge_documents_as_versions and bulk delete, needs confirm: true. Bulk edits over all matching documents reject filters that Paperless would quietly drop. The triage_inbox prompt drafts its changes and waits for your approval before writing anything.
Two settings are mandatory: PAPERLESS_URL and PAPERLESS_API_KEY. You generate the token from your own profile page inside Paperless. This build targets Paperless-ngx 3.2; on the 2.x line use [email protected] instead. Run it with npx, or pick the Docker image or the Claude Desktop extension.
What it helps with
- pull up every document carrying a given tag
- search inside document text for a phrase
- create a tag with a set colour and apply it in bulk
- reassign documents from one correspondent to another
- strip a PDF password and keep the unlocked copy as a version
Example prompts for the agent
- List every document tagged 'Invoice'
- Find documents that mention 'tax return'
- Create a tag named 'Receipts' with colour #FF0000
How to install Paperless-ngx
Platform CLI
claude mcp add --env PAPERLESS_URL=<PAPERLESS_URL> --env PAPERLESS_API_KEY=<PAPERLESS_API_KEY> --env PAPERLESS_PUBLIC_URL=<PAPERLESS_PUBLIC_URL> --transport stdio paperless-ngx -- npx -y paperless-ngx-mcpReplace <…> with your own values
Platform CLI
codex mcp add paperless-ngx --env PAPERLESS_URL=<PAPERLESS_URL> --env PAPERLESS_API_KEY=<PAPERLESS_API_KEY> --env PAPERLESS_PUBLIC_URL=<PAPERLESS_PUBLIC_URL> -- npx -y paperless-ngx-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"paperless-ngx": {
"command": "npx",
"args": [
"-y",
"paperless-ngx-mcp"
],
"env": {
"PAPERLESS_URL": "<PAPERLESS_URL>",
"PAPERLESS_API_KEY": "<PAPERLESS_API_KEY>",
"PAPERLESS_PUBLIC_URL": "<PAPERLESS_PUBLIC_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"paperless-ngx": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"paperless-ngx-mcp"
],
"env": {
"PAPERLESS_URL": "<PAPERLESS_URL>",
"PAPERLESS_API_KEY": "<PAPERLESS_API_KEY>",
"PAPERLESS_PUBLIC_URL": "<PAPERLESS_PUBLIC_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PAPERLESS_URL=<PAPERLESS_URL> -e PAPERLESS_API_KEY=<PAPERLESS_API_KEY> -e PAPERLESS_PUBLIC_URL=<PAPERLESS_PUBLIC_URL> paperless-ngx npx -y paperless-ngx-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Paperless-ngx
How do I install the Paperless-ngx MCP server in Claude Code?
Run claude mcp add paperless-ngx-mcp -e PAPERLESS_URL=<PAPERLESS_URL> -e PAPERLESS_API_KEY=<PAPERLESS_API_KEY> -- npx -y paperless-ngx-mcp, replacing the URL and token with your own.
What does the Paperless-ngx MCP server do?
It exposes the Paperless-NGX API to your assistant: document search and edits, tags, correspondents, workflows, mail rules, versions and trash.
Which Paperless-ngx version does it support?
Paperless-ngx 3.2. If you run Paperless 2.x, install [email protected].
