Full Paperless-ngx API for AI assistants: search, tag, edit and upload documents, workflows and more
This MCP server provides a “Full Paperless-ngx API” for AI assistants. It enables capabilities around documents and related management, including search, tag, edit, and upload, along with workflows and additional functions described as part of the Paperless-ngx integration.
🛠️ Key Features
Full Paperless-ngx API exposure
Document search
Tagging support
Document editing
Document upload
Workflow support
🚀 Use Cases
Allow AI assistants to locate documents in Paperless-ngx
Enable assistants to categorize documents via tags
Support assistant-driven updates to document content
Let assistants upload new documents into Paperless-ngx
Manage and execute workflow-related tasks
⚡ Developer Benefits
AI assistants can interact with Paperless-ngx through MCP
Enables end-to-end document operations (search, tag, edit, upload) plus workflows
⚠️ Limitations
Only details provided are the Paperless-ngx API scope and listed operations; no further constraints or performance characteristics are specified.
A Model Context Protocol server for Paperless-NGX. Exposes the full Paperless-NGX REST API to AI assistants — documents, tags, correspondents, document types, custom fields, storage paths, saved views, share links and bundles, workflows, mail accounts and rules, document versions, notes, trash, and tasks.
Claude Code triaging a Paperless-ngx inbox with paperless-ngx-mcp
Why this one?
Complete, and it stays that way. A CI test checks every endpoint in Paperless's /api/schema/ against the tools here and fails when upstream adds one that is neither wrapped nor deliberately skipped.
Tested against real Paperless. The end-to-end suite runs the tools against a live Paperless-ngx 3.2.1 container, not mocks.
Asks before it breaks things. Every delete_* tool, empty_trash, merge_documents_as_versions and bulk delete require confirm: true; bulk edits across "all matching documents" refuse filters Paperless would silently ignore; and the triage_inbox prompt proposes changes and waits for your go-ahead before writing anything.
Install it your way:npx, a Docker image, a one-click Claude Desktop extension, or the official MCP Registry.
Compatibility
Targets Paperless-ngx 3.2 (tested against 3.2.1). Older Paperless versions are not supported — use paperless-ngx-mcp@3.1.1 for Paperless 2.x. The package major version tracks the Paperless-ngx major it targets; there are no 1.x or 2.x releases.
Quick Start
The server is published to npm as paperless-ngx-mcp. You can run it with npx — no clone or build required.
Claude Code
bash
claude mcp add paperless --scope user \
--env PAPERLESS_URL=https://your-paperless-instance \
--env PAPERLESS_API_KEY=your-api-token \
-- npx -y paperless-ngx-mcp
Drop --scope user to install for the current project only. See claude mcp add --help for more options.
Download paperless-ngx-mcp.mcpb from the latest release and double-click it, or install it from Settings → Extensions. Claude Desktop asks for your Paperless URL and API token.
Claude Desktop, Cursor, Cline, and other MCP clients
The buttons install placeholder values; replace PAPERLESS_URL and PAPERLESS_API_KEY afterwards. Or add this to your client's MCP config file (e.g. claude_desktop_config.json, ~/.cursor/mcp.json, ~/.config/cline/mcp.json):
⚠️ merge_documents_as_versions — merged documents stop existing on their own
mcp__paperless__process_*
process_mail_account — fetches mail now and runs its rules (which may delete or move mail on the server)
A read-only allowlist is therefore: list_*, get_*, search_*, download_*, test_*. Write access without destructive operations: add create_*, update_*, edit_*_bulk, upload_*, rebuild_*, post_document, email_document, restore_from_trash, acknowledge_tasks. delete_*, merge_*, process_* and empty_trash should require explicit user approval.
Prompts
The server also registers MCP prompts — reusable, parameterized instructions that surface as slash commands in clients like Claude Code (e.g. /mcp__paperless__triage_inbox).
triage_inbox
Walks the assistant through inbox triage: gather existing tags / correspondents / document types, propose metadata for each inbox document preferring existing items, present a confirmation table, and only apply changes after the user replies apply. New correspondents / types / tags are flagged (NEW) so you can veto creations before they happen.
Argument:
limit (optional, default 25): maximum number of inbox documents to triage in one pass.
Notable tool details
edit_documents_bulk
Perform bulk operations on multiple documents.
Parameters:
Selection: documents (array of IDs), orall: true + filters with optional excluded_documents. filters takes Paperless document filter names such as correspondent__id, tags__id__all, document_type__id, title_content or query — not list_documents' tool arguments. Keys Paperless doesn't know are refused (it would otherwise ignore them and select every document), a preview query catches invalid values, and the result reports matched_documents. all: true isn't supported for merge, split, delete_pages, edit_pdf or remove_password.
method: one of set_correspondent, set_document_type, set_storage_path, add_tag, remove_tag, modify_tags, modify_custom_fields, delete, reprocess, set_permissions, merge, split, rotate, delete_pages, edit_pdf, remove_password
// Add a tag to multiple documentsedit_documents_bulk({ documents: [1, 2, 3], method: "add_tag", tag: 5 })
// Merge documentsedit_documents_bulk({
documents: [6, 7, 8],
method: "merge",
metadata_document_id: 6,
delete_originals: true,
})
// Split a document into partsedit_documents_bulk({ documents: [9], method: "split", pages: "[1-2,3-4,5]" })
// Modify multiple tags at onceedit_documents_bulk({
documents: [10, 11],
method: "modify_tags",
add_tags: [1, 2],
remove_tags: [3, 4],
})
// Move every document from a duplicate correspondent (12) to the canonical one (34)edit_documents_bulk({ all: true, filters: { correspondent__id: 12 }, method: "set_correspondent", correspondent: 34 })
// Unlock a password-protected PDF, keeping the result as a new versionedit_documents_bulk({ documents: [55], method: "remove_password", password: "…", update_document: true })
Paperless answers remove_password with OK even when it skips a document (its latest version isn't encrypted) or the password is wrong, so check the document's versions afterwards.
Workflows
A workflow — its triggers plus the actions they run — is what Paperless executes; create_workflow builds one in a single call. Standalone triggers and actions (create_workflow_trigger / create_workflow_action) do nothing on their own, and Paperless deletes unattached ones whenever any workflow is updated.
Action types: 1 assignment, 2 removal, 3 email, 4 webhook, 5 password removal, 6 move to trash, 7 remote OCR, 8 apply AI suggestions. Remote OCR needs a consumption-started trigger; AI suggestions need a trigger other than consumption-started.
update_workflow changes only what you pass — but a triggers or actions list replaces the whole list: entries with an id are updated, entries without one are created, and omitted ones are deleted. get_workflow output can be edited and sent straight back.
PDF passwords of password-removal actions are always returned masked (**********). Sending the masked list back keeps the stored passwords; a new action needs the real ones.
Which filters a trigger checks depends on its type: sources, filter_path and filter_mailrule only work on consumption-started triggers (type 1); tag/correspondent/type/storage-path filters, filter_custom_field_query and content matching only on added/updated/scheduled (types 2–4); filter_filename on every type.
Document versions
upload_document_version adds a new file to an existing document (a signed copy, a corrected scan), and merge_documents_as_versions folds duplicate documents into one. Content, search, downloads and get_document_metadata follow the latest version, but page_count and the file names on get_document describe the original (root) version — check get_document_content to see whether the current version is readable.
Reading and editing single documents
get_filing_options returns every tag, correspondent, document type, storage path and custom field (id + name) in one call — fetch it once before filing instead of guessing IDs.
update_document takes add_tags / remove_tags to change single tags without touching the rest. tags replaces the whole list. Every tag change returns tag_changes: { added, removed }.
list_documents takes ids to read several known documents in one call, and fields (on get_document too) to return only what you need, e.g. ["title", "tags"].
get_document_content takes max_chars and offset for long documents; the result then reports total_chars and truncated. Paperless stores the text without page boundaries, so slices are by characters.
search_documents searches the full-text index (mode: query for advanced syntax — the default, text for plain words, title for titles only). The index can lag behind; list_documents with search matches substrings straight from the database.
file accepts base64-encoded contents (the universal method — works for any deployment, since the bytes travel over the wire) or an absolute file path that the server reads from its own filesystem. The path option only works when the MCP server runs on the same machine as the file (local/stdio deployments); for a remote server, use base64.
Upload is asynchronous. By default the tool returns a task UUID (track it with list_tasks). Set poll: true to wait for the consumer to finish and get the result in one call — the new document_id on success, or the consumer error on failure. poll_timeout_seconds (default 30, max 300) caps the wait; raise it for large scans where OCR is slow.
Matching algorithms
create_tag, create_correspondent, create_document_type, and create_storage_path accept a matching_algorithm (0–6). Workflow triggers accept 0–5 (no Automatic):
Value
Meaning
0
None
1
Any word
2
All words
3
Exact match
4
Regular expression
5
Fuzzy word
6
Automatic
Since Paperless-ngx 3.2, Automatic matching only assigns when the classifier is confident enough (PAPERLESS_CLASSIFIER_MATCH_THRESHOLD, default 0.6), and regular-expression matching gives up after PAPERLESS_MATCH_REGEX_TIMEOUT_SECONDS (default 0.1 s) — raise it if regex rules miss on long documents.
Running the MCP Server
stdio (default)
The default mode. The server communicates over stdio — that's what every MCP client config in the Quick Start uses. You usually never run this manually; the MCP client launches it for you.
If you do want to run it directly (e.g. for debugging):
bash
# via env vars (recommended)
PAPERLESS_URL=http://localhost:8000 PAPERLESS_API_KEY=xxx npx -y paperless-ngx-mcp
# or via CLI flags
npx -y paperless-ngx-mcp --baseUrl http://localhost:8000 --token xxx
HTTP (Streamable HTTP transport)
Use the --http flag to expose the server over HTTP. --port defaults to 3000.
The first request (an initialize call) creates a session and returns an Mcp-Session-Id header; subsequent requests must send that header back to reuse the same session. Transports are kept in an in-memory Map, so this only works for single-instance deployments.
GET /mcp streams server-initiated messages for a session; DELETE /mcp terminates it and evicts it from the map. Both require a valid Mcp-Session-Id header.
A legacy GET /sse + POST /messages SSE transport is also exposed for clients that don't yet support the streamable transport.
Session limits
Every session holds its own MCP server instance (~3.5 MB), and the HTTP port has no authentication — so sessions are bounded:
Flag
Environment variable
Default
Purpose
--maxSessions
PAPERLESS_MAX_SESSIONS
50
Concurrent sessions allowed. Past this, initialize is refused with HTTP 503.
--sessionIdleMinutes
PAPERLESS_SESSION_IDLE_MINUTES
30
Evict a session after this long with no activity.
A client that is actively connected — including one holding a GET /mcp stream open — is never evicted, no matter how long it stays idle. Only genuinely abandoned sessions are reclaimed.
Because sessions live in memory, --http only works for single-instance deployments. Do not expose the port to an untrusted network: there is no auth, and it binds all interfaces.
Error Handling
Tool calls return clear errors when:
PAPERLESS_URL or PAPERLESS_API_KEY is missing or wrong
The Paperless-NGX server is unreachable
The underlying API rejects the operation — Paperless's own message is passed through (e.g. {"non_field_errors":["password not specified"]} (HTTP 400)), while HTML error pages are reduced to the status line
A Paperless call doesn't finish within 90 seconds (downloads are exempt); for a timed-out write the error warns that the change may already have been applied
Tool parameters fail validation
Development
You only need this section if you're modifying the server itself. End users should follow the Quick Start instead — there's no need to clone or build.
bash
git clone https://github.com/cubinet-code/paperless-ngx-mcp.git
cd paperless-ngx-mcp
npm install # install dependencies
npm run start # run the server with tsx (no build step)
npm run build # compile TypeScript to build/
npm test# unit tests (node:test + tsx)
npm run inspect # build, then launch @modelcontextprotocol/inspector
npm run start accepts the same flags / env vars as the built binary.
End-to-end tests
E2E tests spin up a real Paperless-NGX container via Docker Compose:
bash
npm run test:e2e:up # start the test stack (paperless + redis)
npm run test:e2e # run the e2e suite against it
npm run test:e2e:down # tear down and remove volumes
Runs against ghcr.io/paperless-ngx/paperless-ngx:3.2.1.
axios — HTTP client (with keep-alive agents, a 60s idle timeout and a 90s per-request deadline)
API Documentation
This MCP server wraps endpoints from the Paperless-NGX REST API. See the official API documentation for details on the underlying behaviour and field semantics.