paperless-mcp
Provides read access to a Paperless-ngx instance, allowing users to list schemas, search documents, retrieve document metadata and extracted custom fields, summarize field values, and run saved views while respecting each caller's Paperless permissions.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
paperless-mcp
An MCP server for Paperless-ngx. It lets a Claude session find documents and read their extracted custom fields — amounts, dates, providers — without returning document text.
Each caller acts as their own Paperless user. The server can see only what that user can.
Five read tools:
list_schema,search_documents,get_document,summarize_field,run_saved_view.Documents tagged
private, and documents with no type, are returned as metadata only. Configured document types are left out entirely.Served over streamable HTTP at
/mcp, behind Cloudflare Access; the Access JWT is re-validated in-process.
Design and specs
The design and the EARS specs are kept in a separate, private specification repository,
under the segment document-access (prefix DACC). Code and tests here cite those specs as
@spec DACC-…, so a citation is a pointer to the requirement a line implements even when the
spec itself isn't public.
Related MCP server: paperless-ngx-mcp
Configuration
Environment variables, all prefixed PAPERLESS_MCP_:
Variable | Meaning |
| Base URL the server calls Paperless on. |
| Base URL used to build the document links it returns. |
| Cloudflare Access team domain, e.g. |
| The Access application's audience tag. |
| JSON list of |
| JSON list of document type names left out of every result. Default |
| JSON list of |
| Listen address. Default |
The server refuses to start, and exits non-zero, when the identity map is unusable, when an
identity holds more than view permissions in Paperless, or when the private tag or an
excluded document type does not exist. It re-checks permissions hourly and exits if they
have grown.
Each tool call writes one JSON audit line to stdout: who called, which Paperless user it acted as, the tool, the document ids returned. Never a value, a title or a search string. A call refused before a tool runs (an unknown tool, arguments that do not fit the schema) writes the same line with the error class.
Image
build-push.yml publishes registry.home.chaosbit.dev/paperless-mcp on every push to
main, and only after ci.yml passes on that commit. It reads four secrets from the
release environment, which only main can deploy to; they're listed at the top of the
workflow.
Development
uv sync
uv run ruff check .
uv run mypy src
uv run pytest -qLicense
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only search of your Sortio knowledge graph (files and entities) for Claude and ChatGPT.
Search and read the Claude Platform documentation and API reference.
Provides metadata information to AI agents through the search API.
Give Claude only the Google Drive files you choose. Every action logged.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables managing Paperless-NGX documents, tags, correspondents, and document types via natural language. Supports document searching, downloading, uploading, and bulk editing.212 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables Claude AI to interact with Paperless-NGX document management through natural language, offering 50 tools for full CRUD operations and management.205 npmMIT
- AlicenseNot gradedqualityDmaintenanceConnects Claude to a self-hosted Paperless-ngx document archive, enabling natural language search, retrieval, and taxonomy browsing of documents.MIT
- FlicenseNot gradedqualityDmaintenanceEnables MCP clients to search and retrieve documents from a self-hosted Paperless-ngx instance, including full OCR'd text and metadata, with read-only access enforced via API tokens.-