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, and dates, and read the text of any document — without being able to 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

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 (whoosh syntax) plus filters for title, content, tags, correspondent, document type, storage path, and dates
get_document	One document's full metadata, with optional inline text content
list_tags	Tags, filterable by name
list_correspondents	Correspondents, filterable by name
list_document_types	Document types, filterable by name
list_storage_paths	Storage paths, filterable by name
list_custom_fields	Custom field definitions

Every document result includes a uri like paperless://documents/42 that can be read as an MCP resource.

Resources

Resource	Contents
paperless://documents/{id}	The document's full text
paperless://documents/{id}/thumbnail	A WebP thumbnail of the first page

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.