Paperless MCP

Paperless-NGX document management over MCP: search, tag, upload, and read documents; manage tags, correspondents, document types, and custom fields.

Documentation | PyPI | Docker

Features

• Document search & retrieval — full-text and filtered list queries against Paperless-NGX, plus access to extracted OCR text, metadata, thumbnails, and original-file downloads via short-lived signed URLs.

• Tag, correspondent, document-type, custom-field management — full CRUD and bulk-edit for every classification dimension Paperless exposes.

• Document lifecycle — upload new documents, update fields, attach notes, and inspect audit history and AI-suggested tags/correspondents/types.

• Operational introspection — saved views, storage paths, share links, background tasks (with wait_for_task), statistics, and remote Paperless-NGX version.

• MCP tools — 50 LLM-visible tools with Lucide icons and read-only gating; see src/paperless_mcp/tools/.

• MCP resources — 20 URIs exposing documents and domain collections; see src/paperless_mcp/resources/.

• Read-only mode — flip PAPERLESS_MCP_READ_ONLY=true to disable every mutating tool at startup.

What you can do with it

With this server mounted in an MCP client (Claude, etc.), you can:

• "Find last quarter's invoices from ACME." Composes search_documents with a correspondent filter, then streams matches via paperless://documents/{id}/content.

• "Tag these three documents as 'reviewed' and move them to the Accounting correspondent." Uses bulk_edit_documents in a single call.

• "Upload this PDF and wait until OCR finishes." Composes upload_document + wait_for_task so the assistant only reports back once the document is indexed.

• "What changed on document 4213 in the last week?" Reads paperless://documents/4213/history and summarises the audit trail.

• "Give me a time-limited link to the original file for document 982." Calls create_download_link — the URL is valid for PAPERLESS_MCP_DOWNLOAD_LINK_TTL_SECONDS and does not expose the API token.

Installation

From PyPI

pip install pvliesdonk-paperless-mcp

If you add optional extras via the PROJECT-EXTRAS-START / PROJECT-EXTRAS-END sentinels in pyproject.toml, document them below:

• pip install pvliesdonk-paperless-mcp[docs] — pulls in mkdocs-material and mkdocstrings[python] for building the documentation site locally (uv run mkdocs serve).

From source

git clone https://github.com/pvliesdonk/paperless-mcp.git
cd paperless-mcp
uv sync --all-extras --dev

Docker

docker pull ghcr.io/pvliesdonk/paperless-mcp:latest

A compose.yml ships at the repo root as a starting point — copy .env.example to .env, edit, and docker compose up -d.

Linux packages (.deb / .rpm)

Download .deb or .rpm packages from the GitHub Releases page. Both install a hardened systemd unit; env configuration is sourced from /etc/paperless-mcp/env (copy from the shipped /etc/paperless-mcp/env.example).

Claude Desktop (.mcpb bundle)

Download the .mcpb bundle from the GitHub Releases page and double-click to install, or run:

mcpb install paperless-mcp-<version>.mcpb

Claude Desktop prompts for required env vars via a GUI wizard — no manual JSON editing needed.

Quick start

paperless-mcp serve                                # stdio transport
paperless-mcp serve --transport http --port 8000   # streamable HTTP

For library usage (embedding the domain logic without the MCP transport), import from the paperless_mcp package directly — see src/paperless_mcp/domain.py for the entry point scaffold.

Configuration

All settings come from environment variables with the PAPERLESS_MCP_ prefix.

Required

Optional (with defaults)

See the Transport & Auth section below for the inherited transport, auth, and logging variables.

Transport & Auth

The following variables are inherited unchanged from fastmcp-server-template:

Tools

Documents

get_document, list_documents, search_documents, and update_document include a web_url field pointing to the document in the Paperless UI (e.g. https://paperless.example.com/documents/42/). Set PAPERLESS_MCP_PAPERLESS_PUBLIC_URL if the public URL differs from the API URL; otherwise the API URL is used.

Paginated tools return next/previous as bare page=N markers (never full URLs) — callers pass page=N explicitly when walking pages. None means no further page.

Tags

Correspondents

Document Types

Custom Fields

Observability

Downloads

Resources

Shared framework variables

Inherited from fastmcp-pvl-core across all services built on the template:

GitHub secrets

CI workflows reference three repository secrets. Configure them via Settings → Secrets and variables → Actions or with gh secret set:

gh secret set RELEASE_TOKEN
gh secret set CODECOV_TOKEN
gh secret set CLAUDE_CODE_OAUTH_TOKEN

GITHUB_TOKEN is auto-provided — no action needed.

Local development

The PR gate (matches CI):

uv run pytest -x -q                                  # tests
uv run ruff check --fix . && uv run ruff format .    # lint + format
uv run mypy src/ tests/                              # type-check

Pre-commit runs a subset of the gate on each commit; see .pre-commit-config.yaml for details, or CLAUDE.md for the full Hard PR Acceptance Gates.

Troubleshooting

Moving a scaffolded project

uv sync creates .venv/bin/* scripts with absolute shebangs pointing at the venv Python. If you move the repo after scaffolding (mv /old/path /new/path), uv run pytest fails with ModuleNotFoundError: No module named 'fastmcp' because the stale shebang resolves to a different interpreter than the venv's site-packages.

Fix:

rm -rf .venv
uv sync --all-extras --dev

uv run python -m pytest also works as a one-shot workaround (bypasses the stale entry-script shim).

uv.lock refresh after copier update

When copier update introduces new dependencies (e.g. a new extra added to pyproject.toml.jinja), CI runs uv sync --frozen which fails against a stale lockfile. Run uv lock locally and commit the refreshed uv.lock alongside accepting the copier-update PR.

Links

• Documentation

• llms.txt

• FastMCP

• fastmcp-pvl-core

Domain configuration

The full domain env-var surface is documented under Configuration above (Required / Optional tables). Those PAPERLESS_MCP_* fields are composed inside src/paperless_mcp/config.py between the CONFIG-FIELDS-START / CONFIG-FIELDS-END sentinels; env reads go through fastmcp_pvl_core.env(_ENV_PREFIX, "SUFFIX", default) so naming stays consistent.

Key design decisions

• Read-only gating at startup, not per-call. PAPERLESS_MCP_READ_ONLY=true skips registration of every mutating tool so they simply aren't part of the advertised tool surface — clients can't invoke a write that will be refused.

• Download links are signed and time-limited. create_download_link mints a short-lived URL (default 300 s, clamped to [30, 3600]) that proxies through the MCP server, so the Paperless API token never leaves the host.

• HTTP layer retries idempotent reads only. PAPERLESS_MCP_HTTP_RETRIES applies to GETs on 5xx/network errors; writes never retry automatically, to avoid double-applying bulk edits or uploads.

• Tool icons come from Lucide. Every tool carries a Lucide icon hint so MCP clients that render icons (Claude Desktop) get a coherent visual surface — see src/paperless_mcp/tools/_icons.py.

• Models accept unknown upstream fields. Pydantic models use lenient validation for list-endpoint responses so newer Paperless-NGX versions don't break the client (the Document.some_future_paperless_field test pins this behaviour).

• No prompts ship in v1. prompts.py is intentionally empty; prompts land as concrete user-workflow patterns emerge in practice.