Skip to content
MCP server

Paperless MCP

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

Install
Pricing
Open source
Runs
Locally or Remotely
Version
3.0.0
Listing updated
5 days ago

About Paperless MCP

Paperless MCP is an open-source MCP server. It can run locally on your machine or as a hosted remote server.

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

Install

Run in a terminal

claude mcp add paperless-mcp --env PAPERLESS_MCP_API_TOKEN='<PAPERLESS_MCP_API_TOKEN>' -- uvx pvliesdonk-paperless-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_API_TOKEN": "<PAPERLESS_MCP_API_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_API_TOKEN": "<PAPERLESS_MCP_API_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "paperless-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_API_TOKEN": "<PAPERLESS_MCP_API_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_API_TOKEN": "<PAPERLESS_MCP_API_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_API_TOKEN": "<PAPERLESS_MCP_API_TOKEN>"
      }
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • 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_TOKENPaperless 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_TOKENSingle 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_SECRETOIDC 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_KEYSigning 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_TOKENPaperless 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.

Pricing

Open source

Prices change. Check pvliesdonk.github.io before you buy.

Paperless MCP FAQ

Is Paperless MCP free?

Yes. Paperless MCP is open source, so you can use and self-host it for free.

How do I add Paperless MCP to Claude Code?

Run this command in your terminal: claude mcp add paperless-mcp --env PAPERLESS_MCP_API_TOKEN='<PAPERLESS_MCP_API_TOKEN>' -- uvx pvliesdonk-paperless-mcp

Where this comes from

  • Description: from the official MCP Registry entry.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers