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.

Related MCP server: paperlessngx-mcp

Tools

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.