Paperless MCP
Paperless MCP exposes a Paperless-NGX instance over MCP so clients can search, read, upload, organize, and inspect documents and related metadata within the API token's permissions.
Documents: list and filter documents, full-text search, similarity search, get metadata, OCR text in bounded sections, thumbnails, notes, audit history, and classifier suggestions.
Document changes: update or delete documents, bulk-edit documents, add/delete notes, and run bulk operations such as tagging, moving, OCR redo, permissions, merge/split/rotate/delete pages.
Uploads and tasks: upload documents as base64 payloads, receive a task UUID, list/get background tasks, and wait for task completion.
Organizing metadata: CRUD for tags, correspondents, document types, custom fields, and storage paths; bulk operations for tags, correspondents, and document types.
Instance inspection: list saved views and share links, get statistics, check the newest upstream Paperless release, and report server/upstream version info.
Limits: tools act only as the configured Paperless user/token, do not administer Paperless users/mail rules/workflows, and read Paperless's own OCR text.
Allows interaction with a Paperless-NGX API server, providing tools for managing documents, tags, correspondents, document types, and custom fields in a Paperless-NGX instance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Paperless MCP find all invoices from ACME from last quarter"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Paperless MCP
Paperless-NGX over MCP: search, read, upload and tag documents; manage correspondents and types.
Documentation | Config wizard | PyPI | Docker
This server gives an MCP client (Claude Desktop, Claude Code, claude.ai or any other) the API of an existing Paperless-NGX instance: one tool per Paperless operation, with the instance's own permissions. It adds no document store and no workflow of its own; what a task does with the tools is up to the model.
Documents: full-text and filtered search, metadata, notes, history, thumbnails, and the OCR text in bounded sections.
Organising: create, change, delete and bulk-edit tags, correspondents, document types and custom fields, and bulk operations on documents.
Files: upload documents for Paperless to consume and wait on the task; over HTTP, one-time transfer links move whole files outside the model's context.
The instance: statistics, saved views, storage paths, share links, background tasks and the installed and newest Paperless versions.
With the server connected, a client can handle requests such as:
"Find last quarter's invoices from ACME." The model searches with a correspondent filter, then reads each match's text.
"Tag these three documents as 'reviewed' and move them to the Accounting correspondent." One bulk edit.
"Upload this PDF and wait until OCR finishes." An upload, then a wait on its consume task, so the answer comes once the document is indexed.
"What changed on document 4213 in the last week?" The document's audit log.
Does it fit?
What the server can reach, what it changes and who gets in is set out in the security model; the block below says who it serves and where it stops.
For: people who already keep their documents in Paperless-NGX and want an MCP client to search, read, file and organise them.
Reaches: one Paperless-NGX instance over its REST API, with one API token; the security model lists what that token lets the tools read and change.
Limits: the tools can do only what the token's Paperless user may do. They don't administer Paperless (users, mail rules, workflows), and the text they read is Paperless's own OCR.
Related MCP server: paperless-agent-toolkit
Quick start
Pick the client you use. Each line installs the released version; the Get started tutorials carry on from there.
Claude Desktop. Download the .mcpb bundle from the releases page and open it with Claude Desktop (or Settings › Extensions › Advanced settings › Install Extension…). Claude Desktop asks for the required settings itself. Tutorial.
Claude Code. Two commands inside Claude Code; the second asks for a scope. Tutorial.
/plugin marketplace add pvliesdonk/claude-plugins
/plugin install paperless-mcp@pvliesdonkA client that runs a command (stdio). To register it in Claude Code, see the Claude Code tutorial.
uv tool install "pvliesdonk-paperless-mcp"
paperless-mcp serveA server for remote clients (streamable HTTP). A remote server connects the clients.
docker run --rm -p 8000:8000 --env-file .env ghcr.io/pvliesdonk/paperless-mcp:latestA compose.yml ships at the repository root and runs as-is: copy .env.example to .env, then docker compose up -d. Deploy covers authentication, OIDC, a reverse proxy and system packages (.deb/.rpm on the releases page). The server answers /health and /health/ready outside the MCP mount, and its get_server_info tool reports the running version.
uv tool install "pvliesdonk-paperless-mcp[debug]"addsdebugpy, for attaching a debugger to a running server.
Configuration
Everything is configured through environment variables with the PAPERLESS_MCP_ prefix. The ones most installs set:
Variable | Default | Required | Description |
| (none) | Yes | Base URL of the Paperless-NGX REST API, without a trailing slash. |
| (none) | Yes | Paperless service-account token used for outbound API requests. |
| (none) | No | Public Paperless UI URL for user-visible links; defaults to PAPERLESS_URL. |
Every variable the server reads, the shared ones included, is in the configuration reference; .env.example lists the same surface in copy-paste form, and the config wizard writes one for your deployment.
Documentation
Security model: what the server can reach, what it changes and who gets in.
Get started: a first success with your client.
Deploy: Docker, authentication, OIDC, reverse proxy.
Use: the features, for real tasks.
Reference: configuration, tools, resources, prompts, command line.
Upgrade: release channels, and what an upgrade changes for your clients and your data.
Contribute: local development, secrets, where a fix belongs;
CONTRIBUTING.mdandSECURITY.mdat the root.
Design decisions
Read-only deployments use tool visibility, not a domain switch. Set
PAPERLESS_MCP_TOOLS_DENY(orPAPERLESS_MCP_TOOLS_ALLOW) to hide the mutating tools, includingcreate_upload_linkwhen transfers are enabled. The template applies visibility last inmake_server, so hidden tools leavetools/listand are rejected ontools/call. Clients cannot invoke a write that will be refused, and the rule lives in one place for every server built on this template.HTTP layer retries idempotent reads only.
PAPERLESS_MCP_HTTP_RETRIESapplies to GETs on 5xx/network errors; writes never retry automatically, to avoid double-applying bulk edits or uploads.Tool icons come from
Lucide. Every tool carries aLucideicon hint so MCP clients that render icons (Claude Desktop) get a coherent visual surface. Seesrc/paperless_mcp/tools/_icons.py.Paperless API compatibility: requests prefer payload version 10, with automatic version 9 fallback for Paperless 2.x after an explicit version rejection. Tasks include structured results and timing data while retaining the legacy fields. Saved-view visibility flags can now be
null; Python consumers must handle that value. See task tools.Models accept unknown upstream fields.
Pydanticmodels use lenient validation for list-endpoint responses so newer Paperless-NGX versions do not break the client (theDocument.some_future_paperless_fieldtest pins this behaviour).No prompts ship in v1.
prompts.pyis intentionally empty; prompts land as concrete user-workflow patterns emerge in practice.
Links
Documentation and its llms.txt
FastMCP and fastmcp-pvl-core, which this server is built on
fastmcp-server-template, which generated this repository
Available Tools
50 toolsadd_document_noteAdd Document NoteC
Append a note to a document.
Inputs: note (required), document_id (required). Returns: id, note, user, created
bulk_edit_correspondentsBulk Edit CorrespondentsCDestructive
Apply a bulk operation to a set of correspondents.
Inputs: ids (required), operation (required), parameters. Returns: result
bulk_edit_documentsBulk Edit DocumentsADestructive
Apply a bulk operation to a set of documents.
Paperless writes the change before answering OK, then queues the
search-index rebuild as a background task. A following
search_documents call can therefore miss the edited documents for
seconds to minutes, while list_documents and get_document
reflect the change at once. Metadata operations queue a
bulk_update task: find it with
list_tasks(task_type="bulk_update") and wait_for_task on its
task_id to wait for full-text search to catch up.
Inputs: ids (required), operation (required), parameters. Returns: result
bulk_edit_document_typesBulk Edit Document TypesCDestructive
Apply a bulk operation to a set of document types.
Inputs: ids (required), operation (required), parameters. Returns: result
bulk_edit_tagsBulk Add or Remove TagsCDestructive
Apply a bulk operation to a set of tags.
Inputs: ids (required), operation (required), parameters. Returns: result
create_correspondentCreate CorrespondentD
Create a new correspondent.
Inputs: body (required). Returns: id, name, slug, match, +6 more
create_custom_fieldCreate Custom FieldA
Create a new custom field.
extra_data depends on data_type:
string,longtext,integer,boolean,float,date,url,documentlink— unused; omit or passnull.monetary— optional{"default_currency": "USD"}(ISO-4217).select—extra_datarequired:{"select_options": [{"label": "Low"}, {"label": "Medium"}]}. Paperless assigns each option a stableidon creation.
Unknown shapes are rejected by Paperless with a 400.
Inputs: body (required). Returns: id, name, data_type, extra_data
create_document_typeCreate Document TypeC
Create a new document type.
Inputs: body (required). Returns: id, name, slug, match, +5 more
create_tagCreate TagC
Create a new tag.
Inputs: body (required). Returns: id, name, slug, color, +8 more
delete_correspondentDelete CorrespondentCDestructiveIdempotent
Delete a correspondent.
Inputs: correspondent_id (required). Returns: result
delete_custom_fieldDelete Custom FieldCDestructiveIdempotent
Delete a custom field.
Inputs: field_id (required). Returns: result
delete_documentDelete Document PermanentlyDDestructiveIdempotent
Delete a document.
Inputs: document_id (required). Returns: result
delete_document_noteDelete Document NoteBDestructiveIdempotent
Remove a note from a document.
Inputs: note_id (required), document_id (required). Returns: result
delete_document_typeDelete Document TypeCDestructiveIdempotent
Delete a document type.
Inputs: document_type_id (required). Returns: result
delete_tagDelete TagCDestructiveIdempotent
Delete a tag.
Inputs: tag_id (required). Returns: result
get_correspondentGet CorrespondentARead-onlyIdempotent
Fetch a correspondent by ID.
Inputs: correspondent_id (required). Returns: id, name, slug, match, +6 more
get_custom_fieldGet Custom FieldARead-onlyIdempotent
Fetch a custom field by ID.
Inputs: field_id (required). Returns: id, name, data_type, extra_data
get_documentGet DocumentARead-onlyIdempotent
Fetch one document by ID.
OCR content is stripped to keep responses small. Call
get_document_content for a bounded preview, or use
create_download_link with the content variant when available.
Inputs: document_id (required). Returns: id, tags, added, notes, +16 more
get_document_contentGet Document TextARead-onlyIdempotent
Return the OCR'd text content of a document.
Documents such as books and technical standards can run to millions of
characters, so each call is capped at 20,000. A partial result opens
with a marker naming the character range returned, the document's full
length, and the offset to pass to read the next section; text that
fits under the cap is returned whole with no marker.
Inputs: document_id (required), offset, max_chars. Returns: result
get_document_historyGet Document Audit LogBRead-onlyIdempotent
Return the audit history for a document.
Inputs: document_id (required). Returns: result
get_document_metadataGet Document File DetailsBRead-onlyIdempotent
Return technical metadata for a document (checksums, filenames, etc.).
Inputs: document_id (required). Returns: lang, archive_size, original_size, media_filename, +8 more
get_document_notesList Document NotesBRead-onlyIdempotent
Return notes attached to a document.
Inputs: document_id (required). Returns: result
get_document_suggestionsSuggest Tags, Correspondent and TypeBRead-onlyIdempotent
Return Paperless's classifier suggestions for a document.
Inputs: document_id (required). Returns: tags, dates, storage_paths, correspondents, +1 more
get_document_thumbnailGet Document ThumbnailBRead-onlyIdempotent
Return the document's thumbnail as inline image content.
Inputs: document_id (required).
get_document_typeGet Document TypeBRead-onlyIdempotent
Fetch a document type by ID.
Inputs: document_type_id (required). Returns: id, name, slug, match, +5 more
get_remote_versionCheck for Paperless UpdatesARead-onlyIdempotent
Check whether a newer release of Paperless-NGX exists upstream.
Answers the newest release published on GitHub, and whether it is newer
than the connected instance -- not the version installed on that
instance. The two coincide only while the instance is up to date.
Call get_server_info for the installed version.
Inputs: no named parameters. Returns: ``/api/remote_version/``: the newest release published on GitHub. ``version`` i…
get_saved_viewGet Saved ViewARead-onlyIdempotent
Fetch a saved view by ID.
Visibility flags are null when payload v10 omits those preferences.
Inputs: view_id (required). Returns: id, name, owner, page_size, +5 more
get_server_infoServer InfoARead-only
Report wrapper and upstream version info for paperless-mcp. Returns server_name, server_version, core_version (fastmcp-pvl-core), and (when configured) an upstream version block. Useful for verifying a deployment matches the expected build.
Inputs: no named parameters. Returns: object
get_statisticsGet Paperless StatisticsARead-onlyIdempotent
Fetch collection-level statistics.
Inputs: no named parameters. Returns: inbox_tag, tag_count, current_asn, character_count, +6 more
get_storage_pathGet Storage PathARead-onlyIdempotent
Fetch a storage path by ID.
Inputs: storage_path_id (required). Returns: id, name, path, slug, +6 more
get_tagGet TagARead-onlyIdempotent
Fetch a tag by ID.
Inputs: tag_id (required). Returns: id, name, slug, color, +8 more
get_taskGet Background TaskARead-onlyIdempotent
Fetch a task by UUID. Returns None if no such task exists.
Inputs: task_uuid (required). Returns: result
list_correspondentsList CorrespondentsCRead-onlyIdempotent
List correspondents.
Each row's last_correspondence is the date of the correspondent's
newest document, or null when it has none; ordering accepts it.
Inputs: page, ordering, page_size, name__icontains. Returns: next, count, results, previous
list_custom_fieldsList Custom FieldsCRead-onlyIdempotent
List custom fields.
Inputs: page, ordering, page_size. Returns: next, count, results, previous
list_documentsList DocumentsARead-onlyIdempotent
List documents with optional filters. Returns one page.
Per-document OCR content is stripped to keep results small. Use
get_document_content for a bounded preview of one result.
notes[].note and custom_fields[].value are always stripped
from listings. The metadata refs
(note ids, timestamps, custom-field ids) are retained so callers can
detect presence; use get_document or get_document_notes to read
those values.
Inputs: page, tags, ordering, page_size, +4 more. Returns: next, count, results, previous
list_document_typesList Document TypesCRead-onlyIdempotent
List document types.
Inputs: page, ordering, page_size, name__icontains. Returns: next, count, results, previous
list_saved_viewsList Saved ViewsBRead-onlyIdempotent
List saved views.
Visibility flags are null when payload v10 omits those preferences.
Inputs: page, page_size. Returns: next, count, results, previous
list_storage_pathsList Storage PathsDRead-onlyIdempotent
List storage paths.
Inputs: page, ordering, page_size. Returns: next, count, results, previous
list_tagsList TagsDRead-onlyIdempotent
List tags.
Inputs: page, ordering, page_size, name__icontains. Returns: next, count, results, previous
list_tasksList Background TasksARead-onlyIdempotent
List Paperless Celery tasks.
Defaults to unacknowledged tasks only (set include_acknowledged=True
or acknowledged=True to see acknowledged ones). Returns one page,
newest first.
Pass task_type to filter by the kind of work — "bulk_update"
is the search-index rebuild that bulk_edit_documents queues, so
that tool's deferred indexing can be waited on with wait_for_task.
Version 10 adds task_type, trigger_source, structured result_data,
related_document_ids and timing fields. Statuses retain their uppercase
spelling. Legacy task_name, type, result and related_document remain
compatibility projections; use the v10 fields for full detail.
Inputs: page, status, page_size, task_type, +2 more. Returns: next, count, results, previous
search_documentsSearch DocumentsARead-onlyIdempotent
Full-text search documents.
Per-hit OCR content is stripped. Use get_document_content for a
bounded preview of one hit. Use more_like for similarity search.
notes[].note and custom_fields[].value are always stripped
from search hits; fetch them via get_document or
get_document_notes when needed.
Inputs: query (required), page, more_like, page_size. Returns: next, count, results, previous
update_correspondentUpdate CorrespondentCIdempotent
Patch selected fields on a correspondent.
Inputs: patch (required), correspondent_id (required). Returns: id, name, slug, match, +6 more
update_custom_fieldUpdate Custom FieldAIdempotent
Patch selected fields on a custom field definition.
extra_data shape depends on data_type:
monetary— optional{"default_currency": "USD"}(ISO-4217).select—extra_data.select_optionsreplaces the current list wholesale. To preserve existing values, include each existing option with its server-assignedid:{"select_options": [{"id": "abc", "label": "Low"}, ...]}. Omitting an option'sidcreates a new option; dropping an option from the list deletes it and any document values referencing it. A patch withoutextra_data, such as a rename, keeps the current options: the server reads them and sends them back with their ids.
See create_custom_field for the full extra_data shape table.
Inputs: patch (required), field_id (required). Returns: id, name, data_type, extra_data
update_documentUpdate DocumentAIdempotent
Patch selected fields on a document.
The response strips OCR content. Use get_document_content or a
transfer link when the updated text is needed.
Inputs: patch (required), document_id (required). Returns: id, tags, added, notes, +16 more
update_document_typeUpdate Document TypeCIdempotent
Patch selected fields on a document type.
Inputs: patch (required), document_type_id (required). Returns: id, name, slug, match, +5 more
update_tagUpdate TagBIdempotent
Patch selected fields on a tag.
Inputs: patch (required), tag_id (required). Returns: id, name, slug, color, +8 more
upload_documentUpload DocumentB
Upload a document. Returns the task UUID for polling via get_task.
Inputs: filename (required), content_base64 (required), tags, title, +5 more. Returns: task_id
wait_for_taskWait for Task to FinishARead-onlyIdempotent
Poll until the task reaches a terminal state or times out.
Inputs: task_uuid (required), timeout_seconds. Returns: Task details with structured results and compatible legacy projections.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 50 tools
Tools are grouped clearly by resource and action, so get_document, get_document_content, get_document_metadata, and get_document_notes are easy to distinguish despite all targeting a document by ID. The only mild overlap is list_documents versus search_documents, though their descriptions explain the metadata-filter vs full-text distinction.
The set overwhelmingly follows a snake_case verb_noun pattern with predictable singular/plural forms: list_*, get_*, create_*, update_*, delete_*, bulk_edit_*. Minor deviations like add_document_note versus get_document_notes and upload_document instead of create_document are understandable but break the otherwise consistent pattern.
50 tools is a very large surface for an agent to select from, even though Paperless has many resource types. Several resource groups are only read-only (storage paths, saved views, share links), which makes the high count feel heavier than necessary.
Documents, correspondents, tags, document types, and custom fields have solid CRUD coverage, and document retrieval/search is thorough. However, storage paths, saved views, and share links expose only list/get operations, and share-link creation is referenced but not present as a tool, leaving notable lifecycle gaps.
Maintenance
Related MCP Connectors
Document processing over MCP: merge, split and compress PDFs, run OCR, extract document text.
Search, read and cite documents. Add, replace and delete files with write access. OAuth required.
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
Political Comms documentation MCP server: search docs, query the docs filesystem. No auth.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with a paperless-ngx document management system through MCP tools, allowing document search, retrieval, upload, and metadata management via natural language.1-
- FlicenseNot gradedqualityDmaintenanceMCP server for Paperless-ngx document management, enabling search, OCR content access, metadata updates, tag/correspondent/type management, and duplicate detection via natural language.1-
- FlicenseNot gradedqualityDmaintenanceEnables MCP clients to search and retrieve documents from a self-hosted Paperless-ngx instance, including full OCR'd text and metadata, with read-only access enforced via API tokens.-
- AlicenseNot gradedqualityBmaintenanceEnables per-user document management and retrieval in Paperless-ngx by authenticating each MCP call with the caller's own Keycloak identity, providing the same 44 tools as the upstream server while maintaining per-person isolation.MIT