Paperless Agent Toolkit

MCP server for Paperless-ngx document management, plus reusable agent skills built on top of it (e.g. auto-filing documents tagged TODO).

This repo has two parts:

• src/paperless_mcp/ — an MCP server exposing Paperless-ngx as tools: list/search documents, read full OCR content, update metadata, manage tags/correspondents/ document types, find duplicates. Works with any MCP-compatible client, not just Claude.
• .claude/skills/ — Claude Code skills that use those tools to carry out a workflow end-to-end (currently: paperless-todo-cleanup, which files every TODO-tagged document — title, correspondent, document type, tags — then clears the tag).

Setup

Requires Python >=3.10.

pip install -e .

Set two environment variables (Paperless UI → Settings → API Tokens for the token):

export PAPERLESS_URL="http://<paperless-host>:8000"
export PAPERLESS_TOKEN="<your-api-token>"

Run the server directly (stdio transport):

python -m paperless_mcp.server

Registering with an MCP client

For Claude Code, add it as a project-scoped MCP server (values from a .env or your shell, not hardcoded) — e.g. via claude mcp add, or directly in .mcp.json:

{
  "mcpServers": {
    "paperless-ngx": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "paperless_mcp.server"],
      "env": {
        "PAPERLESS_URL": "http://<paperless-host>:8000",
        "PAPERLESS_TOKEN": "<your-api-token>"
      }
    }
  }
}

PAPERLESS_TOKEN is a credential — keep it in a gitignored config (e.g. Claude Code's .claude/settings.local.json or your own .env), never in a tracked file.

Tools

Tool	Purpose
list_documents	Search/filter documents (tag, correspondent, type, full-text query, tag count); paginates internally
get_document	Full document detail, including OCR content and checksum
update_document	Set title/correspondent/document_type/tags/created/content; unknown names auto-create
add_tags / remove_tags	Adjust a document's tags without touching the rest
delete_document	Delete a document (requires confirm=True)
find_duplicate_documents	Group documents by identical file checksum
list_tags / list_correspondents / list_document_types	Enumerate existing values, for reuse before creating new ones
create_tag / create_correspondent / create_document_type	Create explicitly (usually unnecessary — update_document auto-creates)
rename_tag / rename_correspondent / rename_document_type	Rename by current name or id
delete_tag / delete_correspondent / delete_document_type	Delete by name or id (requires confirm=True)
get_instance_url	Return the configured Paperless base URL, e.g. for building web UI links

Skills

• paperless-todo-cleanup — processes every TODO-tagged document: picks a descriptive title, sets correspondent/document type where determinable, applies 3–4 tags (reusing existing ones over creating new), then drops the TODO tag. Invoke with /paperless-todo-cleanup in Claude Code.