paperless-mcp
Read-only Paperless-ngx MCP server for searching, browsing, and reading documents and metadata; it cannot create, change, or delete anything.
Full-text search documents with tantivy syntax, find similar documents, and filter by title, content, tags, inbox, correspondent, document type, storage path, custom fields, and dates.
Retrieve a document’s full metadata, notes, custom-field values, and optional inline text, plus resource/web URLs.
List and filter tags, correspondents, document types, storage paths, and custom fields by IDs or name.
Read MCP resources for a document’s full text, WebP thumbnail, and notes as JSON.
Query custom field values with exact, in, exists, isnull, range, comparison, and string/link operators.
Paginate and order results; use Paperless error explanations when requests are refused.
Allows read-only interaction with a Paperless-ngx document archive, enabling full-text search, metadata retrieval, and listing of tags, correspondents, document types, storage paths, and custom fields.
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 documents about rent from 2023"
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
A read-only MCP server for your paperless-ngx document archive. It lets an AI assistant search your documents by full text, tags, correspondents, dates, and custom field values, find documents similar to one, find unfiled documents, and read the text and notes of any document. It cannot change or delete anything.
Setup
uv syncYou'll need an API token from your paperless-ngx instance: log in, open your profile (the person icon in the top right), and copy or generate the API token there.
The server is configured entirely through environment variables:
export PAPERLESS_URL=https://paperless.example.com
export PAPERLESS_TOKEN=your-api-tokenRelated MCP server: paperlessngx-mcp
Connecting a client
For Claude Code:
claude mcp add paperless \
-e PAPERLESS_URL=https://paperless.example.com \
-e PAPERLESS_TOKEN=your-api-token \
-- uv run --directory /path/to/paperless-mcp paperless-mcpFor Claude Desktop, add this to claude_desktop_config.json:
{
"mcpServers": {
"paperless": {
"command": "uv",
"args": ["run", "--directory", "/path/to/paperless-mcp", "paperless-mcp"],
"env": {
"PAPERLESS_URL": "https://paperless.example.com",
"PAPERLESS_TOKEN": "your-api-token"
}
}
}
}Tools
Tool | What it does |
| Full-text search (tantivy syntax) or documents similar to one, plus filters for title, content, tags (all, any, or none of them, or whether it has any), the inbox, correspondent, document type, and storage path (by ID, or whether one is set), custom field values, and dates |
| One document's full metadata, with its notes, custom field values, and optional inline text content |
| Tags, filterable by name or IDs |
| Correspondents with the date of their newest document, filterable by name or IDs |
| Document types, filterable by name or IDs |
| Storage paths, filterable by name or IDs |
| Custom field definitions with the options of select fields, filterable by name or IDs |
Every tool declares itself read-only to the client, with the MCP
read_only_hint annotation and a read tag. The ids filter on the list
tools resolves the IDs on a document back to names.
Every document result includes a uri like paperless://documents/42 that
can be read as an MCP resource, and a web_url that opens the document in the
Paperless web UI.
The custom_field_query filter on search_documents takes a list of
conditions, each a custom field, an operator, and a value, and matches
documents that meet all of them or any of them. It supports every operator
of Paperless's
custom field query
except NOT, nested groups, and date-part operators like year__exact. It
needs paperless-ngx 2.13 or later.
When Paperless refuses a request, the tool's error carries Paperless's own
explanation, such as Paperless returned 404: No Document matches the given query. Other unexpected errors reach the client without their details. The
server gives up on a request to Paperless after 30 seconds.
Resources
Resource | Contents |
| The document's full text |
| A WebP thumbnail of the first page |
| The document's notes, as a JSON list |
Security
This server is read-only by construction: it only ever issues GET requests to paperless-ngx, and it exposes no way to create, modify, or delete documents. It performs no authentication of its own. Anyone who can reach the running server can read whatever the configured token can read, so treat the token accordingly and run the server close to where you use it.
Container image
The container image serves the MCP server over HTTP on port 9000. Build it
with docker buildx bake, which reads docker-bake.hcl, the same file CI
publishes from:
docker buildx bake --load
docker run --rm -p 9000:9000 ghcr.io/chrisguidry/paperless-mcp:devAvailable Tools
7 toolsget_documentGet documentARead-only
Get a single document's full metadata, with its notes and custom fields.
The preferred way to read a document's text is its MCP resource at paperless://documents/{document_id}.
Inputs: document_id (required), include_content. Returns: A document's full metadata.
list_correspondentsList correspondentsARead-only
List correspondents: the people and organizations that documents are from or to.
Use the returned IDs with search_documents(correspondent_id=...).
Inputs: ids, page, page_size, name_contains. Returns: One page of correspondents.
list_custom_fieldsList custom fieldsARead-only
List the custom fields defined in the archive.
get_document returns a document's custom field values by field ID. A select field's value is the id of one of the field's select_options. Search custom field values with search_documents, using a query like "custom_fields.value:overdue".
Inputs: ids, page, page_size, name_contains. Returns: One page of custom fields.
list_document_typesList document typesARead-only
List document types, like invoice or receipt.
Use the returned IDs with search_documents(document_type_id=...).
Inputs: ids, page, page_size, name_contains. Returns: One page of document types.
list_storage_pathsList storage pathsARead-only
List storage paths: the filing locations of documents.
Use the returned IDs with search_documents(storage_path_id=...).
Inputs: ids, page, page_size, name_contains. Returns: One page of storage paths.
list_tagsList tagsARead-only
List tags.
Use the returned IDs with search_documents(tag_ids=[...]).
Inputs: ids, page, page_size, name_contains. Returns: One page of tags.
search_documentsSearch documentsARead-only
Search and filter documents in the archive.
All parameters combine as AND conditions, except that query and
more_like_document_id cannot be used together. query is full-text
search over document contents using tantivy syntax: plain terms ("electric
bill"), boolean operators ("chase AND (mortgage OR escrow)"), field
prefixes ("correspondent:university", "type:invoice", "tag:unpaid",
"created:[2020 to 2023]"), and wildcards ("electr*"). Notes and custom
fields are structured fields with dotted paths: "notes.note:reimbursed",
"custom_fields.value:overdue", "custom_fields.name:warranty". Plain terms
do NOT match them, only titles and content. Full-text results include a
search_hit with highlights.
more_like_document_id finds documents whose text is similar to one
document's, ranked by similarity in search_hit.rank. The results leave
out that document itself, and the other filters narrow them. Leave
ordering unset to keep the ranking.
To find unfiled documents, use is_in_inbox=true, or has_tags, has_correspondent, has_document_type, or has_storage_path set to false.
custom_field_query compares custom field values, like "Amount over 100"
or "Warranty Expires before 2027-01-01". Every field type supports exact,
in, exists, and isnull. Date, integer, float, and monetary fields add gt,
gte, lt, lte, and range. String, URL, long text, and monetary fields add
icontains, istartswith, and iendswith. Document link fields add contains.
Paperless refuses an operator that the field's type does not support.
Each result carries a uri, which you can read as an MCP resource for the
document's full text, and a web_url that links to the document in the
Paperless web UI. Read paperless://documents/{id}/notes for a document's
notes, or call get_document for its notes and custom field values.
Inputs: page, query, tag_ids, has_tags, +19 more. Returns: One page of documents matching a search.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct operation: one broad search, one document fetch, and five entity-specific listers. The list_* tools could superficially look alike, but each names a clearly different Paperless resource and explicitly cross-references the corresponding search parameter, leaving no realistic misselection risk.
All tools follow a clean verb_noun snake_case pattern (search_documents, get_document, list_tags, list_correspondents, list_document_types, list_storage_paths, list_custom_fields). No mixed casing or stray verbs.
Seven tools is well-scoped: one flexible search, one detail fetcher, and the minimum set of lookup tools needed to resolve IDs for filtering. Nothing appears redundant or padding the surface.
The surface is entirely read-only: search, get, and list exist but there is no upload_document, update_document, delete_document, or create/update for tags, correspondents, document types, storage paths, or custom fields. Core retrieval workflows are covered, but lifecycle operations for a document management archive are notably absent.
Maintenance
Related MCP Connectors
Read-only MCP server exposing a user ORANO library to their own AI agent.
Query your own PDFs and documents from any MCP client. Every answer cites the page it came from.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAn Agentic RAG MCP Server that transforms Paperless-ngx into a conversational document assistant, enabling LLMs to search, filter, and summarize documents using natural language.5GPL 3.0
- FlicenseAqualityBmaintenanceA privacy-first MCP server for Paperless-ngx that lets an LLM agent search, organize, tag, and reference documents without exposing full text unless explicitly requested.13-
- FlicenseAqualityCmaintenanceMCP server for Paperless-ngx document management. Enables AI models to search, retrieve, update documents and manage metadata.7-
- AlicenseNot gradedqualityCmaintenanceA read-only and write MCP server for Paperless-ngx, enabling document listing, metadata retrieval, and creation of tags, correspondents, document types, and sorting workflows via natural language.MIT