Paperless MCP Server

by pvliesdonkio.github.pvliesdonk/paperless-mcpv3.0.0

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

1Pythonstdioremoteofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active12d ago

Install Paperless MCP server

claude mcp add pvliesdonk-paperless -e PAPERLESS_MCP_API_TOKEN='<paperless-mcp-api-token>' -- uvx pvliesdonk-paperless-mcp

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

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

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

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

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

Add to .vscode/mcp.json in your workspace.

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

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

Configuration

Variable	Required	Secret	Description
PAPERLESS_MCP_SHUTDOWN_GRACE_S	—	—	Seconds 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_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	—	yes	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	—	yes	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	—	yes	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	—	—	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_APP_DOMAIN	—	—	MCP Apps iframe domain, used for CSP sandboxing. Overrides the host derived from `base_url`.
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_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.
PAPERLESS_MCP_LOG_LEVEL	—	—	Log 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_FORMAT	—	—	Log 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_URL	—	—	Base URL of the Paperless-NGX REST API, without a trailing slash. The server refuses to start without it.
PAPERLESS_MCP_API_TOKEN	—	yes	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_TRANSFER_TTL_DEFAULT_S	—	—	Link lifetime in seconds when the caller requests no explicit TTL.
PAPERLESS_MCP_TRANSFER_TTL_MAX_S	—	—	Ceiling in seconds a caller-requested link TTL is clamped to.
PAPERLESS_MCP_TRANSFER_GRACE_TTL_S	—	—	Post-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_S	—	—	Crashed-handler reclaim window in seconds for an in-flight reservation.
PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES	—	—	Maximum size in bytes of a single upload.

Freshness

Active — last maintenance signal 12d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-09-28 · 12d ago · GitHub
Latest release
2026-09-21 · 19d ago · GitHub · v3.0.0
Package published
no data · npm/PyPI
Registry entry updated
2026-09-21 · 19d ago · official registry · v3.0.0

FAQ

›How do I install the Paperless MCP server in Claude Code?

Run: claude mcp add pvliesdonk-paperless -e PAPERLESS_MCP_API_TOKEN='<paperless-mcp-api-token>' -- uvx pvliesdonk-paperless-mcp. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Paperless require an API key?

Yes. It expects PAPERLESS_MCP_BEARER_TOKEN, PAPERLESS_MCP_OIDC_CLIENT_SECRET, PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY, PAPERLESS_MCP_API_TOKEN, of which 4 are secrets.

›Can I use Paperless as a remote (hosted) MCP server?

Yes — it offers both a hosted endpoint and a local stdio package.

›Is Paperless in the official MCP registry?

Yes, as io.github.pvliesdonk/paperless-mcp.

Install Paperless MCP server

Install in Claude Code

Install in Cursor

Install in Claude Desktop

Install in VS Code

Install in Windsurf

Configuration

Freshness

FAQ