Paperless MCP server

by pvliesdonk·io.github.pvliesdonk/paperless-mcp·v3.0.0·1 stars

No reviews yet

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

B83/100grade B

Write a review Install

What users say

No reviews yet

Be the first

Safety scan

B83/100

full report

Adoption

Growing

1 stars96 downloads/wk

Reviews

Write one

Nobody has reviewed Paperless MCP yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

Paperless MCP tools (49, 16 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

add_document_note
Append a note to a document.
bulk_edit_correspondents
Apply a bulk operation to a set of correspondents.
bulk_edit_document_types
Apply a bulk operation to a set of document types.
bulk_edit_documents
Apply a bulk operation to a set of documents.
bulk_edit_tags
Apply a bulk operation to a set of tags.
create_correspondentwrite action
Create a new correspondent.
create_custom_fieldwrite action
Create a new custom field.
create_document_typewrite action
Create a new document type.
create_tagwrite action
Create a new tag.
delete_correspondentwrite action
Delete a correspondent.
delete_custom_fieldwrite action
Delete a custom field.
delete_documentwrite action
Delete a document.
delete_document_notewrite action
Remove a note from a document.
delete_document_typewrite action
Delete a document type.
delete_tagwrite action
Delete a tag.
get_correspondent
Fetch a correspondent by ID.
get_custom_field
Fetch a custom field by ID.
get_document
Fetch one document by ID.
get_document_content
Return the OCR'd text content of a document.
get_document_history
Return the audit history for a document.
get_document_metadata
Return technical metadata for a document (checksums, filenames, etc.).
get_document_notes
Return notes attached to a document.
get_document_suggestions
Return Paperless's classifier suggestions for a document.
get_document_thumbnail
Return the document's thumbnail as inline image content.
get_document_type
Fetch a document type by ID.
get_remote_version
Check whether a newer release of Paperless-NGX exists upstream.
get_saved_view
Fetch a saved view by ID.
get_share_link
Fetch a share link by ID.
get_statistics
Fetch collection-level statistics.
get_storage_path
Fetch a storage path by ID.
get_tag
Fetch a tag by ID.
get_task
Fetch a task by UUID. Returns ``None`` if no such task exists.
list_correspondents
List correspondents.
list_custom_fields
List custom fields.
list_document_types
List document types.
list_documents
List documents with optional filters. Returns one page.
list_saved_views
List saved views.
list_share_links
List share links (optionally filtered by document).
list_storage_paths
List storage paths.
list_tags
List tags.
list_tasks
List Paperless Celery tasks.
search_documents
Full-text search documents.
update_correspondentwrite action
Patch selected fields on a correspondent.
update_custom_fieldwrite action
Patch selected fields on a custom field definition.
update_documentwrite action
Patch selected fields on a document.
update_document_typewrite action
Patch selected fields on a document type.
update_tagwrite action
Patch selected fields on a tag.
upload_documentwrite action
Upload a document. Returns the task UUID for polling via `get_task`.
wait_for_task
Poll until the task reaches a terminal state or times out.

Public scan report

scanner v0.1.10 · 2026-10-15 · same rubric, same numbers if you re-run it

no findings

Code scan79 source files scanned25/25
–Live reliabilityno gateway calls yet and no remote to proben/a
–Tool poisoningtools not inspected (local package is not executed); not countedn/a
Auth qualitystatic API keys via environment variables6/15
Maintenancelast push 2 days ago15/15
Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Overall 83/100. Components that don't apply are left out of the denominator. Any critical finding is an F.Rubric Appeal a finding JSON

How Paperless MCP compares

Against every graded Web search MCP server, from our own scans and uptime checks. Updated after each scan run.

Safety score: 83/100; higher than 70% of 3,470 Web search servers
Tools: 49; the typical Web search server has 5
Tools that change things: 33%; typical: 0%. Fewer write tools means less an agent can break
GitHub stars: 1; more than 55% of 1,786 Web search servers
Downloads a week: 96; more than 56% of 827 Web search servers with a package

What its tools let an agent do: 32 read · 6 create · 5 change · 6 delete

Release history: 3 versions in the registry since 2026-09-17, latest 2026-09-21, typically one every 3 days.

Install Paperless MCP in Claude Code, Cursor or VS Code

claude mcp add paperless-mcp -- uvx pvliesdonk-paperless-mcp

Add to Cursor

What the publisher says

From the Paperless MCP repository's README, as published. We do not edit it. Read it on GitHub

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 PAPERLESSMCPBASE_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 waitfortask), 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:

Shortened. The full README is on GitHub.

Nothing above is checked by us. What we check is on the safety report.

Paperless MCP: common questions

Is Paperless MCP server safe?: Mostly: it is graded B (83/100). Read the Paperless MCP safety report
How do I install Paperless MCP?: It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.
Does Paperless MCP need an API key?: Yes. The registry entry asks for PAPERLESS_MCP_API_TOKEN, PAPERLESS_MCP_BEARER_TOKEN, PAPERLESS_MCP_OIDC_CLIENT_SECRET, PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY.
Is Paperless MCP maintained?: The last commit was 22 days ago (2026-10-13). The latest release is v3.0.0.
What can I use instead of Paperless MCP?: Servers from other publishers that do the same job: Free Search MCP server, reMarkable MCP Server and CLIO Web MCP server.
How does Paperless MCP compare with other Web search MCP servers?: safety score 83/100 (higher than 70% of 3,470 Web search servers); tools 49 (the typical Web search server has 5); tools that change things 33% (typical: 0%. Fewer write tools means less an agent can break). Full comparison.

Alternatives to Paperless MCP

Same job from other publishers: the closest match first, then the best rated.

Free Search
No-API-key web search, page fetching and document reading across many engines. Local-first.
not reviewed
Established
B
reMarkable MCP Server
Read, render, search, and manage reMarkable documents through MCP
not reviewed
Established
B
CLIO Web
Provider-fixed web search plus transparent URL, DOI, and document fetching
not reviewed
Established
A
Vadivam Icons
Search 24px outline icons by name, tag, or category and get SVG or framework code.
not reviewed
Established
A
Ref Tools
Token-efficient search for coding agents over public and private documentation.
not reviewed
Established
A

Run it through the gateway

Local package. It runs on your machine, not through the gateway.

Rating: —
Safety grade: B · 83/100
Stars: 1
Downloads/wk: 96
Price: Free
Licence: MIT
Transport: Local · mixed
Version: 3.0.0
Category: Web search
Last release: 2026-10-13

Credentials it needs

PAPERLESS_MCP_KV_STORE_URLPersistent-state backend URL shared by every pvl-core subsystem that needs state. `memory://` is in-process and lost on restart; `file:///path` persists on one server; `redis://`, `dynamodb://` and `mongodb://` each need their matching extra. When unset, defaults to `file:///data/state` (the volume family Docker images mount), or to `memory://` (with a warning) on a host where that directory is not usable.
PAPERLESS_MCP_TOOLS_ALLOWComma-separated explicit tool names this instance exposes; every other tool is hidden from listings and cannot be invoked. Names matching no registered tool are inert. Mutually exclusive with `tools_deny`. Takes effect through `apply_tool_visibility`.
PAPERLESS_MCP_TOOLS_DENYComma-separated explicit tool names hidden from this instance (absent from listings, cannot be invoked). Names matching no registered tool are inert. Mutually exclusive with `tools_allow`. Takes effect through `apply_tool_visibility`.
PAPERLESS_MCP_SERVER_NAMERename this server instance; defaults to the project name.
PAPERLESS_MCP_INSTANCE_DESCRIPTIONConcise routing context that distinguishes this deployment's material or responsibility.
PAPERLESS_MCP_INSTRUCTIONS_EXTRADeployment-specific behavioral policy added to the generated MCP instructions.
PAPERLESS_MCP_INSTRUCTIONSLegacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy).
PAPERLESS_MCP_LOG_LEVELLog level for every logger in the process, FastMCP's included (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG. The unprefixed FASTMCP_LOG_LEVEL still works for one major version and logs a deprecation warning.
PAPERLESS_MCP_LOG_FORMATLog rendering. rich is one colour event key=value line per record, for a terminal; json is one JSON object per record, for a collector. Unset picks rich when stderr is a terminal and json everywhere else, so a container or journald gets JSON with no configuration.
PAPERLESS_MCP_PAPERLESS_URLBase URL of the Paperless-NGX REST API, without a trailing slash. The server refuses to start without it.
PAPERLESS_MCP_API_TOKENsecretPaperless service-account token used for outbound API requests. The server refuses to start without it.
PAPERLESS_MCP_HTTP_TIMEOUT_SECONDSPer-request HTTP timeout in seconds.
PAPERLESS_MCP_HTTP_RETRIESRetries for idempotent requests after network errors or 5xx responses.
PAPERLESS_MCP_DEFAULT_PAGE_SIZEDefault page size for list tools, from 1 through 100.
PAPERLESS_MCP_PAPERLESS_PUBLIC_URLPublic Paperless UI URL for user-visible links; defaults to PAPERLESS_URL.
PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_SLink lifetime in seconds when the caller requests no explicit TTL.
PAPERLESS_MCP_TRANSFER_TTL_MAX_SCeiling in seconds a caller-requested link TTL is clamped to.
PAPERLESS_MCP_TRANSFER_GRACE_TTL_SPost-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it.
PAPERLESS_MCP_TRANSFER_LEASE_SCrashed-handler reclaim window in seconds for an in-flight reservation.
PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTESMaximum size in bytes of a single upload.
PAPERLESS_MCP_SHUTDOWN_GRACE_SSeconds SIGTERM may spend draining in-flight requests before the HTTP server exits. Keep it at or below the termination grace period the orchestrator allows. `0` drops in-flight requests immediately.
PAPERLESS_MCP_BASE_URLPublic base URL of the deployed server, for example `https://mcp.example.com`. Required for OIDC. Also the fallback source of the MCP Apps domain when `app_domain` is unset.
PAPERLESS_MCP_BEARER_TOKENsecretSingle shared bearer token; enables bearer auth unless `bearer_tokens_file` is set, which takes precedence.
PAPERLESS_MCP_OIDC_CONFIG_URLOIDC discovery document URL, for example `https://auth.example.com/.well-known/openid-configuration`.
PAPERLESS_MCP_OIDC_CLIENT_IDOIDC client identifier registered with the provider.
PAPERLESS_MCP_OIDC_CLIENT_SECRETsecretOIDC client secret registered with the provider.
PAPERLESS_MCP_OIDC_AUDIENCEExpected `aud` claim; tokens issued for another audience are rejected.
PAPERLESS_MCP_OIDC_REQUIRED_SCOPESScopes a caller must present, space- or comma-separated. Defaults to `openid` in oidc-proxy mode.
PAPERLESS_MCP_OIDC_ADVERTISED_SCOPESScopes advertised to MCP clients in protected-resource metadata, space- or comma-separated. Overrides the default `openid offline_access`; `oidc_required_scopes` is always added on top. Set this when the registered client is not permitted `offline_access`, or to have clients request extra claim scopes (such as `groups`) without also requiring them in every token.
PAPERLESS_MCP_OIDC_JWT_SIGNING_KEYsecretSigning key for issued tokens; used in oidc-proxy mode only. When unset, the key is derived deterministically from `oidc_client_secret`, so tokens survive a restart. Rotating that secret then invalidates every issued token. Set this explicitly to decouple token validity from secret rotation. Generate with `openssl rand -hex 32`.
PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKENValidate the access token instead of the id token.
PAPERLESS_MCP_KV_STORE_URLPersistent-state backend URL shared by every pvl-core subsystem that needs state. `memory://` is in-process and lost on restart; `file:///path` persists on one server; `redis://`, `dynamodb://` and `mongodb://` each need their matching extra. When unset, defaults to `file:///data/state` (the volume family Docker images mount), or to `memory://` (with a warning) on a host where that directory is not usable.
PAPERLESS_MCP_APP_DOMAINMCP Apps iframe domain, used for CSP sandboxing. Overrides the host derived from `base_url`.
PAPERLESS_MCP_TOOLS_ALLOWComma-separated explicit tool names this instance exposes; every other tool is hidden from listings and cannot be invoked. Names matching no registered tool are inert. Mutually exclusive with `tools_deny`. Takes effect through `apply_tool_visibility`.
PAPERLESS_MCP_TOOLS_DENYComma-separated explicit tool names hidden from this instance (absent from listings, cannot be invoked). Names matching no registered tool are inert. Mutually exclusive with `tools_allow`. Takes effect through `apply_tool_visibility`.
PAPERLESS_MCP_AUTH_MODEExplicit auth-mode override, accepting `remote` or `oidc-proxy` (case- and whitespace-insensitive). When unset the mode is auto-detected from which auth variables are set; the override exists because having all four OIDC variables set is ambiguous between those two modes. Other values are ignored with a warning.
PAPERLESS_MCP_BEARER_TOKENS_FILEPath to a TOML file mapping bearer tokens to subjects; overrides the single-token `bearer_token` mode.
PAPERLESS_MCP_BEARER_DEFAULT_SUBJECTSubject assigned to the single-token bearer mode; ignored when `bearer_tokens_file` is set, since mapped mode carries per-token subjects.
PAPERLESS_MCP_SERVER_NAMERename this server instance; defaults to the project name.
PAPERLESS_MCP_INSTANCE_DESCRIPTIONConcise routing context that distinguishes this deployment's material or responsibility.
PAPERLESS_MCP_INSTRUCTIONS_EXTRADeployment-specific behavioral policy added to the generated MCP instructions.
PAPERLESS_MCP_INSTRUCTIONSLegacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy).
PAPERLESS_MCP_HTTP_PATHMount path for the MCP endpoint; the health routes derive their prefix from it.
PAPERLESS_MCP_HEALTH_DETAILHow much the unauthenticated /health and /health/ready bodies say: status, standard (adds name, version and per-check verdicts), or full (adds redacted reasons; trusted networks only).
PUIDRun the server process as this UID; the container entrypoint reassigns ownership of writable paths to match.
PGIDRun the server process as this GID; pair with PUID to match the owner of a mounted volume.
PAPERLESS_MCP_LOG_LEVELLog level for every logger in the process, FastMCP's included (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG. The unprefixed FASTMCP_LOG_LEVEL still works for one major version and logs a deprecation warning.
PAPERLESS_MCP_LOG_FORMATLog rendering. rich is one colour event key=value line per record, for a terminal; json is one JSON object per record, for a collector. Unset picks rich when stderr is a terminal and json everywhere else, so a container or journald gets JSON with no configuration.
PAPERLESS_MCP_PAPERLESS_URLBase URL of the Paperless-NGX REST API, without a trailing slash. The server refuses to start without it.
PAPERLESS_MCP_API_TOKENsecretPaperless service-account token used for outbound API requests. The server refuses to start without it.
PAPERLESS_MCP_HTTP_TIMEOUT_SECONDSPer-request HTTP timeout in seconds.
PAPERLESS_MCP_HTTP_RETRIESRetries for idempotent requests after network errors or 5xx responses.
PAPERLESS_MCP_DEFAULT_PAGE_SIZEDefault page size for list tools, from 1 through 100.
PAPERLESS_MCP_PAPERLESS_PUBLIC_URLPublic Paperless UI URL for user-visible links; defaults to PAPERLESS_URL.
PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_SLink lifetime in seconds when the caller requests no explicit TTL.
PAPERLESS_MCP_TRANSFER_TTL_MAX_SCeiling in seconds a caller-requested link TTL is clamped to.
PAPERLESS_MCP_TRANSFER_GRACE_TTL_SPost-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it.
PAPERLESS_MCP_TRANSFER_LEASE_SCrashed-handler reclaim window in seconds for an in-flight reservation.
PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTESMaximum size in bytes of a single upload.

Own this server?

Claim it to keep the listing current and reply to reviews. Claiming never changes the grade or hides a review.

Claim listing

Badge for your README

Shows the safety grade and links back to this page. It updates itself after every scan and review.

[![mcp.market](https://mcp.market/badge/pvliesdonk-paperless-mcp.svg)](https://mcp.market/server/pvliesdonk-paperless-mcp)

How the badge works