Paperless MCP

io.github.pvliesdonk/paperless-mcpv2.0.0Search

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

The current version, v2.0.0, was published to the official MCP registry on 2026-09-17. It is distributed as pvliesdonk-paperless-mcp on PyPI and as the Docker image ghcr.io/pvliesdonk/paperless-mcp:v2.0.0, filed under Search by this index, and declares 33 environment variables. Removals and unreachable sources are measured across every server this index tracks, contract drift across the servers that answer in consecutive snapshots; the index's current counts put this record in context.

In-path gate · all MCP tools

Using Paperless MCP in Claude, Cursor, Gemini CLI, Cline, or Zed?

MCP tool contracts can change remotely with no version bump. The mcpindex gate pins each contract and HOLDs the call when it drifts-before your agent acts. Zero credentials. This is not the package install for this server itself (use Install this server for that).

Install the mcpindex gate (one command)

Rewrites your MCP host config so each server launches behind the gate. Inspect first: curl -fsSL https://mcpindex.ai/install.sh | less

uv tool install mcpindex-gate && mcpindex-config-wire

Auditable install path →Watch it hold a drift →

Trust verdict · v1 advisory · method

NOT YET SCREENEDno verdict on file

Verdict not yet evaluated for this tool. The semantic screen takes adversarial cases first; coverage rolls out as the corpus expands (15/150 labels to graduation). The deterministic conformance probe is built but has not yet run on the public corpus, so a recorded verdict here is REVIEW or UNVERIFIED, never a clearing ALLOW. Until a verdict is recorded, an agent should treat this tool as not-yet-cleared and fall back to its own checks. Method: the eval, four-state verdict, honest limits.

Own this server? Screen its description →

That verdict was true at screening time (snapshot 2026-09-17).

Contracts can change after screening, with no version bump. The gate pins Paperless MCP’s tool contracts on first sight and holds any silent change before your agent acts - the check that keeps being true on Tuesday.

See your first HOLD in 2 minutes →

Environment variables

PAPERLESS_MCP_KV_STORE_URL

Persistent-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_ALLOW

Comma-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_DENY

Comma-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_NAME

Rename this server instance; defaults to the project name.

PAPERLESS_MCP_INSTANCE_DESCRIPTION

Concise routing context that distinguishes this deployment's material or responsibility.

PAPERLESS_MCP_INSTRUCTIONS_EXTRA

Deployment-specific behavioral policy added to the generated MCP instructions.

PAPERLESS_MCP_INSTRUCTIONS

Legacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy).

FASTMCP_LOG_LEVEL

Log level for FastMCP internals and app loggers (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG.

FASTMCP_ENABLE_RICH_LOGGING

Rich color output for a terminal; false gives one plain or JSON line per record. Off in the container image and the systemd unit, since neither is a terminal and Rich wraps a structured record at its 80-column fallback.

PAPERLESS_MCP_PAPERLESS_URL

Base URL of the Paperless-NGX REST API, without a trailing slash. The server refuses to start without it.

PAPERLESS_MCP_API_TOKEN

secret

Paperless service-account token used for outbound API requests. The server refuses to start without it.

PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS

Per-request HTTP timeout in seconds.

PAPERLESS_MCP_HTTP_RETRIES

Retries for idempotent requests after network errors or 5xx responses.

PAPERLESS_MCP_DEFAULT_PAGE_SIZE

Default page size for list tools, from 1 through 100.

PAPERLESS_MCP_PAPERLESS_PUBLIC_URL

Public Paperless UI URL for user-visible links; defaults to PAPERLESS_URL.

PAPERLESS_MCP_BASE_URL

Public 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_TOKEN

secret

Single shared bearer token; enables bearer auth unless `bearer_tokens_file` is set, which takes precedence.

PAPERLESS_MCP_OIDC_CONFIG_URL

OIDC discovery document URL, for example `https://auth.example.com/.well-known/openid-configuration`.

PAPERLESS_MCP_OIDC_CLIENT_ID

OIDC client identifier registered with the provider.

PAPERLESS_MCP_OIDC_CLIENT_SECRET

secret

OIDC client secret registered with the provider.

PAPERLESS_MCP_OIDC_AUDIENCE

Expected `aud` claim; tokens issued for another audience are rejected.

PAPERLESS_MCP_OIDC_REQUIRED_SCOPES

Scopes a caller must present, space- or comma-separated. Defaults to `openid` in oidc-proxy mode.

PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES

Scopes 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_KEY

secret

Signing 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_TOKEN

Validate the access token instead of the id token.

PAPERLESS_MCP_KV_STORE_URL

PAPERLESS_MCP_APP_DOMAIN

MCP Apps iframe domain, used for CSP sandboxing. Overrides the host derived from `base_url`.

PAPERLESS_MCP_TOOLS_ALLOW

PAPERLESS_MCP_TOOLS_DENY

PAPERLESS_MCP_AUTH_MODE

Explicit 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_FILE

Path to a TOML file mapping bearer tokens to subjects; overrides the single-token `bearer_token` mode.

PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT

Subject assigned to the single-token bearer mode; ignored when `bearer_tokens_file` is set, since mapped mode carries per-token subjects.

PAPERLESS_MCP_SERVER_NAME

Rename this server instance; defaults to the project name.

PAPERLESS_MCP_INSTANCE_DESCRIPTION

Concise routing context that distinguishes this deployment's material or responsibility.

PAPERLESS_MCP_INSTRUCTIONS_EXTRA

Deployment-specific behavioral policy added to the generated MCP instructions.

PAPERLESS_MCP_INSTRUCTIONS

Legacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy).

PAPERLESS_MCP_HTTP_PATH

Mount path for the MCP endpoint; the health routes derive their prefix from it.

PAPERLESS_MCP_HEALTH_DETAIL

How 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).

PUID

Run the server process as this UID; the container entrypoint reassigns ownership of writable paths to match.

PGID

Run the server process as this GID; pair with PUID to match the owner of a mounted volume.

FASTMCP_LOG_LEVEL

Log level for FastMCP internals and app loggers (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG.

FASTMCP_ENABLE_RICH_LOGGING

PAPERLESS_MCP_PAPERLESS_URL

Base URL of the Paperless-NGX REST API, without a trailing slash. The server refuses to start without it.

PAPERLESS_MCP_API_TOKEN

secret

Paperless service-account token used for outbound API requests. The server refuses to start without it.

PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS

Per-request HTTP timeout in seconds.

PAPERLESS_MCP_HTTP_RETRIES

Retries for idempotent requests after network errors or 5xx responses.

PAPERLESS_MCP_DEFAULT_PAGE_SIZE

Default page size for list tools, from 1 through 100.

PAPERLESS_MCP_PAPERLESS_PUBLIC_URL

Public Paperless UI URL for user-visible links; defaults to PAPERLESS_URL.

MCP quality score · maturity, not trust · methodology

freshness

completeness

installability

documentation

stability

Alternatives in Search

EmpirioLabs AI

ai.empiriolabs/mcp

Every EmpirioLabs model and platform feature as tools: chat, media, search, jobs, GPU Cloud, agents.

Fodda Topic & Trend Research

ai.fodda/topic-research

Trend, stats & insight search across PSFK expert graphs with citable sources.

NetLens

io.github.pzalutski-pixel/netlens

Read any web page as clean, ad-stripped Markdown past robots.txt and bot blocks, plus web search.

Install this server

Claude Desktop (uvx)

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "--",
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "file:///data/state",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<paperless_mcp_tools_allow>",
        "PAPERLESS_MCP_TOOLS_DENY": "<paperless_mcp_tools_deny>",
        "PAPERLESS_MCP_SERVER_NAME": "<paperless_mcp_server_name>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<paperless_mcp_instance_description>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<paperless_mcp_instructions_extra>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<paperless_mcp_instructions>",
        "FASTMCP_LOG_LEVEL": "INFO",
        "FASTMCP_ENABLE_RICH_LOGGING": "true",
        "PAPERLESS_MCP_PAPERLESS_URL": "<paperless_mcp_paperless_url>",
        "PAPERLESS_MCP_API_TOKEN": "<your-paperless_mcp_api_token>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "30.0",
        "PAPERLESS_MCP_HTTP_RETRIES": "2",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "25",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<paperless_mcp_paperless_public_url>",
        "PAPERLESS_MCP_BASE_URL": "<paperless_mcp_base_url>",
        "PAPERLESS_MCP_BEARER_TOKEN": "<your-paperless_mcp_bearer_token>",
        "PAPERLESS_MCP_OIDC_CONFIG_URL": "<paperless_mcp_oidc_config_url>",
        "PAPERLESS_MCP_OIDC_CLIENT_ID": "<paperless_mcp_oidc_client_id>",
        "PAPERLESS_MCP_OIDC_CLIENT_SECRET": "<your-paperless_mcp_oidc_client_secret>",
        "PAPERLESS_MCP_OIDC_AUDIENCE": "<paperless_mcp_oidc_audience>",
        "PAPERLESS_MCP_OIDC_REQUIRED_SCOPES": "openid",
        "PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES": "openid offline_access",
        "PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY": "<your-paperless_mcp_oidc_jwt_signing_key>",
        "PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN": "false",
        "PAPERLESS_MCP_APP_DOMAIN": "<paperless_mcp_app_domain>",
        "PAPERLESS_MCP_AUTH_MODE": "<paperless_mcp_auth_mode>",
        "PAPERLESS_MCP_BEARER_TOKENS_FILE": "<paperless_mcp_bearer_tokens_file>",
        "PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT": "bearer-anon",
        "PAPERLESS_MCP_HTTP_PATH": "/mcp",
        "PAPERLESS_MCP_HEALTH_DETAIL": "standard",
        "PUID": "1000",
        "PGID": "1000"
      }
    }
  }
}

Claude Desktop (Docker)

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--",
        "ghcr.io/pvliesdonk/paperless-mcp:v2.0.0"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "file:///data/state",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<paperless_mcp_tools_allow>",
        "PAPERLESS_MCP_TOOLS_DENY": "<paperless_mcp_tools_deny>",
        "PAPERLESS_MCP_SERVER_NAME": "<paperless_mcp_server_name>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<paperless_mcp_instance_description>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<paperless_mcp_instructions_extra>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<paperless_mcp_instructions>",
        "FASTMCP_LOG_LEVEL": "INFO",
        "FASTMCP_ENABLE_RICH_LOGGING": "true",
        "PAPERLESS_MCP_PAPERLESS_URL": "<paperless_mcp_paperless_url>",
        "PAPERLESS_MCP_API_TOKEN": "<your-paperless_mcp_api_token>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "30.0",
        "PAPERLESS_MCP_HTTP_RETRIES": "2",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "25",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<paperless_mcp_paperless_public_url>",
        "PAPERLESS_MCP_BASE_URL": "<paperless_mcp_base_url>",
        "PAPERLESS_MCP_BEARER_TOKEN": "<your-paperless_mcp_bearer_token>",
        "PAPERLESS_MCP_OIDC_CONFIG_URL": "<paperless_mcp_oidc_config_url>",
        "PAPERLESS_MCP_OIDC_CLIENT_ID": "<paperless_mcp_oidc_client_id>",
        "PAPERLESS_MCP_OIDC_CLIENT_SECRET": "<your-paperless_mcp_oidc_client_secret>",
        "PAPERLESS_MCP_OIDC_AUDIENCE": "<paperless_mcp_oidc_audience>",
        "PAPERLESS_MCP_OIDC_REQUIRED_SCOPES": "openid",
        "PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES": "openid offline_access",
        "PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY": "<your-paperless_mcp_oidc_jwt_signing_key>",
        "PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN": "false",
        "PAPERLESS_MCP_APP_DOMAIN": "<paperless_mcp_app_domain>",
        "PAPERLESS_MCP_AUTH_MODE": "<paperless_mcp_auth_mode>",
        "PAPERLESS_MCP_BEARER_TOKENS_FILE": "<paperless_mcp_bearer_tokens_file>",
        "PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT": "bearer-anon",
        "PAPERLESS_MCP_HTTP_PATH": "/mcp",
        "PAPERLESS_MCP_HEALTH_DETAIL": "standard",
        "PUID": "1000",
        "PGID": "1000"
      }
    }
  }
}

Verdict API

curl -s mcpindex.ai/api/v1/trust/server/io-github-pvliesdonk-paperless-mcp

Free-tier verdict as JSON: decision + dimensions + severity. Call it from your agent before it invokes a tool it just discovered.

Details

version: v2.0.0
category: Search
quality: 95 / 100
operator: pvliesdonk

Listing

Listed from the official MCP registry. Unclaimed by its maintainer. Maintainer? Email us →

Provenance

Each verdict is bound to a hash of the exact description it judged, so a re-crawl that changes the text produces a new record rather than silently inheriting this one. Verdict history is hash-chained and anchored to Bitcoin via OpenTimestamps (latest confirmed at block 967,367). Verify it yourself.

Links

Repository →Website →