Paperless MCP

io.github.pvliesdonk/paperless-mcp · v3.0.0

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

Website Source code Set it up

Connect Runs on your machine

Terminal

claude mcp add paperless-mcp -e PAPERLESS_MCP_KV_STORE_URL=<PAPERLESS_MCP_KV_STORE_URL> -e PAPERLESS_MCP_TOOLS_ALLOW=<PAPERLESS_MCP_TOOLS_ALLOW> -e PAPERLESS_MCP_TOOLS_DENY=<PAPERLESS_MCP_TOOLS_DENY> -e PAPERLESS_MCP_SERVER_NAME=<PAPERLESS_MCP_SERVER_NAME> -e PAPERLESS_MCP_INSTANCE_DESCRIPTION=<PAPERLESS_MCP_INSTANCE_DESCRIPTION> -e PAPERLESS_MCP_INSTRUCTIONS_EXTRA=<PAPERLESS_MCP_INSTRUCTIONS_EXTRA> -e PAPERLESS_MCP_INSTRUCTIONS=<PAPERLESS_MCP_INSTRUCTIONS> -e PAPERLESS_MCP_LOG_LEVEL=<PAPERLESS_MCP_LOG_LEVEL> -e PAPERLESS_MCP_LOG_FORMAT=<PAPERLESS_MCP_LOG_FORMAT> -e PAPERLESS_MCP_PAPERLESS_URL=<PAPERLESS_MCP_PAPERLESS_URL> -e PAPERLESS_MCP_API_TOKEN=<PAPERLESS_MCP_API_TOKEN> -e PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS=<PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS> -e PAPERLESS_MCP_HTTP_RETRIES=<PAPERLESS_MCP_HTTP_RETRIES> -e PAPERLESS_MCP_DEFAULT_PAGE_SIZE=<PAPERLESS_MCP_DEFAULT_PAGE_SIZE> -e PAPERLESS_MCP_PAPERLESS_PUBLIC_URL=<PAPERLESS_MCP_PAPERLESS_PUBLIC_URL> -e PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S=<PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S> -e PAPERLESS_MCP_TRANSFER_TTL_MAX_S=<PAPERLESS_MCP_TRANSFER_TTL_MAX_S> -e PAPERLESS_MCP_TRANSFER_GRACE_TTL_S=<PAPERLESS_MCP_TRANSFER_GRACE_TTL_S> -e PAPERLESS_MCP_TRANSFER_LEASE_S=<PAPERLESS_MCP_TRANSFER_LEASE_S> -e PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES=<PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES> -- uvx pvliesdonk-paperless-mcp==3.0.0

claude_desktop_config.json

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp==3.0.0"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "<PAPERLESS_MCP_KV_STORE_URL>",
        "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>",
        "PAPERLESS_MCP_LOG_LEVEL": "<PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

~/.cursor/mcp.json

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp==3.0.0"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "<PAPERLESS_MCP_KV_STORE_URL>",
        "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>",
        "PAPERLESS_MCP_LOG_LEVEL": "<PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "paperless-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp==3.0.0"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "<PAPERLESS_MCP_KV_STORE_URL>",
        "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>",
        "PAPERLESS_MCP_LOG_LEVEL": "<PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Replace the values in angle brackets with your own. Keys stay on your machine; we never see them.

Tools

This server runs locally, so its tools are listed by your MCP client once it starts.

Environment variables

Name	Description
`PAPERLESS_MCP_KV_STORE_URL` Optional	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…
`PAPERLESS_MCP_TOOLS_ALLOW` Optional	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` Optional	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` Optional	Rename this server instance; defaults to the project name.
`PAPERLESS_MCP_INSTANCE_DESCRIPTION` Optional	Concise routing context that distinguishes this deployment's material or responsibility.
`PAPERLESS_MCP_INSTRUCTIONS_EXTRA` Optional	Deployment-specific behavioral policy added to the generated MCP instructions.
`PAPERLESS_MCP_INSTRUCTIONS` Optional	Legacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy).
`PAPERLESS_MCP_LOG_LEVEL` Optional	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` Optional	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` Optional	Base URL of the Paperless-NGX REST API, without a trailing slash. The server refuses to start without it.
`PAPERLESS_MCP_API_TOKEN` Optional, secret	Paperless service-account token used for outbound API requests. The server refuses to start without it.
`PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS` Optional	Per-request HTTP timeout in seconds.
`PAPERLESS_MCP_HTTP_RETRIES` Optional	Retries for idempotent requests after network errors or 5xx responses.
`PAPERLESS_MCP_DEFAULT_PAGE_SIZE` Optional	Default page size for list tools, from 1 through 100.
`PAPERLESS_MCP_PAPERLESS_PUBLIC_URL` Optional	Public Paperless UI URL for user-visible links; defaults to PAPERLESS_URL.
`PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S` Optional	Link lifetime in seconds when the caller requests no explicit TTL.
`PAPERLESS_MCP_TRANSFER_TTL_MAX_S` Optional	Ceiling in seconds a caller-requested link TTL is clamped to.
`PAPERLESS_MCP_TRANSFER_GRACE_TTL_S` Optional	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` Optional	Crashed-handler reclaim window in seconds for an in-flight reservation.
`PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES` Optional	Maximum size in bytes of a single upload.

Details

Package	`[email protected]` (PYPI, stdio)
Package	`ghcr.io/pvliesdonk/paperless-mcp:v3.0.0` (OCI, streamable-http)
First published	21 Sep 2026
Last updated	21 Sep 2026
Registry name	`io.github.pvliesdonk/paperless-mcp`

Live status

Local install

Installed and run on your own machine, so there is no public endpoint to check.

Pair it with live search

Agents that use Paperless MCP often also need current facts. NestDaddy MCP gives your AI today's internet: web search, real-time breaking news and full page reading in one connector.

See NestDaddy MCP

For maintainers

[![NestDaddy MCP](https://nestdaddy.com/mcp/servers/io-github-pvliesdonk-paperless-mcp/badge.svg)](https://nestdaddy.com/mcp/servers/io-github-pvliesdonk-paperless-mcp)

Add the badge to your README. It turns green while your server passes our daily check. Listing details come from the official MCP registry; update them there.

Listing data from the official MCP registry. Status and tools from NestDaddy's daily check. Browse all MCP servers.

Connect Runs on your machine

Tools

Environment variables

Details

More files and documents servers See all