Skip to main content
Glama
paperless-mcp

paperless-mcp

by chrisguidry

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 sync

You'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-token

Related 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-mcp

For 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

search_documents

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

get_document

One document's full metadata, with its notes, custom field values, and optional inline text content

list_tags

Tags, filterable by name or IDs

list_correspondents

Correspondents with the date of their newest document, filterable by name or IDs

list_document_types

Document types, filterable by name or IDs

list_storage_paths

Storage paths, filterable by name or IDs

list_custom_fields

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

paperless://documents/{id}

The document's full text

paperless://documents/{id}/thumbnail

A WebP thumbnail of the first page

paperless://documents/{id}/notes

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:dev

Available Tools

7 tools
get_documentGet documentA
Read-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 correspondentsA
Read-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 fieldsA
Read-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 typesA
Read-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 pathsA
Read-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 tagsA
Read-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 documentsA
Read-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

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      An Agentic RAG MCP Server that transforms Paperless-ngx into a conversational document assistant, enabling LLMs to search, filter, and summarize documents using natural language.
      5
      GPL 3.0
    • F
      license
      A
      quality
      B
      maintenance
      A 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
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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