Paperless MCP

Paperless-NGX over MCP: search, read, upload and tag documents; manage correspondents and types.

Documentation | Config wizard | PyPI | Docker

Features

• File transfer links: Download document files and full OCR Markdown over HTTP. Upload files, including Markdown, through the same transfer route. Set PAPERLESS_MCP_BASE_URL to enable the tools. File bytes stay outside model context. See file transfer links.
• Document search & retrieval: full-text and filtered list queries against Paperless-NGX, plus access to extracted OCR text, metadata, and thumbnails.
• Tag, correspondent, document-type, custom-field management: full CRUD and bulk-edit for every classification dimension Paperless exposes.
• Document lifecycle supports uploads, field changes, notes, audit history, and AI-suggested tags/correspondents/types.
• Operational introspection covers saved views, storage paths, share links, background tasks (with wait_for_task), statistics, and an upstream release check for Paperless-NGX.
• MCP tools: 49 LLM-visible tools with Lucide icons; see src/paperless_mcp/tools/.
• MCP resources: 16 URIs exposing bounded document previews and domain collections; see src/paperless_mcp/resources/.

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 reads bounded previews with get_document_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.

Every tool and resource is listed in the documentation site: Tools and Resources. The Paperless variables the server reads are in Configuration.

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]: installs 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 --all-groups

Docker

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

To run the newest merged code instead of the newest release, use the rolling edge tag. It is rebuilt on every merge to main and carries no version identity. See Image tags for the full tag list.

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

A compose.yml ships at the repo root and runs as-is: copy .env.example to .env, then docker compose up -d. It publishes port 8000 on the host and assumes no reverse proxy; Docker Compose covers the configuration split, the domain sentinel blocks, and a Traefik overlay.

To attach a remote Python debugger (development only; the protocol is unauthenticated), see Remote debugging.

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, with no manual JSON editing needed.

For manual Claude Desktop configuration and setup options, see Claude Desktop deployment.

Release channels

Artifacts ship on three channels. Each row lists exactly what that channel publishes.

Pre-releases reach PyPI so that a candidate's .mcpb bundle installs: the bundle points at PyPI rather than carrying the code. Ordinary installers never see them, because a PEP 440 resolver skips pre-releases unless the requirement pins one or you pass --pre. Ask for a candidate by name with pip install pvliesdonk-paperless-mcp==X.Y.ZrcN. PyPI spells it in the PEP 440 canonical form, while tags use SemVer. Rolling pointers are ordering-aware, so a patch release cut from an old release/X.Y branch never moves latest-style tags back to older content, and a candidate for an already-released version never moves rc. See Release process for the full model.

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 the project's domain modules under src/paperless_mcp/ for entry points.

Server info