SERVER

Paperless MCP

Rank #9,137

io.github.pvliesdonk/paperless-mcp

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

3 versions

1 GitHub stars

by pvliesdonk (7 servers)View repository ↗

First listed

Apr 24, 2026

Last publish date

Sep 21, 2026

PURPOSE

What you can do with Paperless MCP

Paperless MCP is a Model Context Protocol (MCP) server published by pvliesdonk. It ranks #9,137 of 144,396 active servers on MCP Toplist, and its repository has 1 GitHub stars. Paperless MCP is listed across 2 registries — Official MCP and Glama, with 3 tracked versions. It was first listed on Apr 24, 2026 and most recently updated on Sep 21, 2026.

Not verifiedMCP Toplist has not yet written a checked profile for this server, so the paragraph above is assembled from registry data only. The repository README is the authority on what it does.

CAPABILITIES AND LIMITATIONS

What Paperless MCP can and cannot do

Not verifiedMCP Toplist has not catalogued this server's tools or limitations. The repository README lists them.

REQUIREMENTS

What you need before using Paperless MCP

DeclaredNo credentialsNo credentials declared

The registry listing declares no required environment variables or authentication. This is declared metadata, not a verified install — the repository README is the authority.

Declared by the Official MCP Registry, last synced Oct 16, 2026. Not independently verified by MCP Toplist.

Declared in the registry install config

PAPERLESS_MCP_KV_STORE_URL · optional
PAPERLESS_MCP_TOOLS_ALLOW · optional
PAPERLESS_MCP_TOOLS_DENY · optional
PAPERLESS_MCP_SERVER_NAME · optional
PAPERLESS_MCP_INSTANCE_DESCRIPTION · optional
PAPERLESS_MCP_INSTRUCTIONS_EXTRA · optional
PAPERLESS_MCP_INSTRUCTIONS · optional
PAPERLESS_MCP_LOG_LEVEL · optional
PAPERLESS_MCP_LOG_FORMAT · optional
PAPERLESS_MCP_PAPERLESS_URL · optional
PAPERLESS_MCP_API_TOKEN · optional
PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS · optional
PAPERLESS_MCP_HTTP_RETRIES · optional
PAPERLESS_MCP_DEFAULT_PAGE_SIZE · optional
PAPERLESS_MCP_PAPERLESS_PUBLIC_URL · optional
PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S · optional
PAPERLESS_MCP_TRANSFER_TTL_MAX_S · optional
PAPERLESS_MCP_TRANSFER_GRACE_TTL_S · optional
PAPERLESS_MCP_TRANSFER_LEASE_S · optional
PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES · optional
PAPERLESS_MCP_SHUTDOWN_GRACE_S · optional
PAPERLESS_MCP_BASE_URL · optional
PAPERLESS_MCP_BEARER_TOKEN · optional
PAPERLESS_MCP_OIDC_CONFIG_URL · optional
PAPERLESS_MCP_OIDC_CLIENT_ID · optional
PAPERLESS_MCP_OIDC_CLIENT_SECRET · optional
PAPERLESS_MCP_OIDC_AUDIENCE · optional
PAPERLESS_MCP_OIDC_REQUIRED_SCOPES · optional
PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES · optional
PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY · optional
PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN · optional
PAPERLESS_MCP_APP_DOMAIN · optional
PAPERLESS_MCP_AUTH_MODE · optional
PAPERLESS_MCP_BEARER_TOKENS_FILE · optional
PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT · optional
PAPERLESS_MCP_HTTP_PATH · optional
PAPERLESS_MCP_HEALTH_DETAIL · optional
PUID · optional
PGID · optional

INSTALLATION AND FIRST TASK

Connect Paperless MCP and confirm it works

Python package (PyPI)

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

Replace each placeholder with your own value before saving.

Docker image

claude mcp add paperless-mcp -e "PAPERLESS_MCP_SHUTDOWN_GRACE_S=<your PAPERLESS_MCP_SHUTDOWN_GRACE_S>" -e "PAPERLESS_MCP_BASE_URL=<your PAPERLESS_MCP_BASE_URL>" -e "PAPERLESS_MCP_BEARER_TOKEN=<your PAPERLESS_MCP_BEARER_TOKEN>" -e "PAPERLESS_MCP_OIDC_CONFIG_URL=<your PAPERLESS_MCP_OIDC_CONFIG_URL>" -e "PAPERLESS_MCP_OIDC_CLIENT_ID=<your PAPERLESS_MCP_OIDC_CLIENT_ID>" -e "PAPERLESS_MCP_OIDC_CLIENT_SECRET=<your PAPERLESS_MCP_OIDC_CLIENT_SECRET>" -e "PAPERLESS_MCP_OIDC_AUDIENCE=<your PAPERLESS_MCP_OIDC_AUDIENCE>" -e "PAPERLESS_MCP_OIDC_REQUIRED_SCOPES=<your PAPERLESS_MCP_OIDC_REQUIRED_SCOPES>" -e "PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES=<your PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES>" -e "PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY=<your PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY>" -e "PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN=<your PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN>" -e "PAPERLESS_MCP_KV_STORE_URL=<your PAPERLESS_MCP_KV_STORE_URL>" -e "PAPERLESS_MCP_APP_DOMAIN=<your PAPERLESS_MCP_APP_DOMAIN>" -e "PAPERLESS_MCP_TOOLS_ALLOW=<your PAPERLESS_MCP_TOOLS_ALLOW>" -e "PAPERLESS_MCP_TOOLS_DENY=<your PAPERLESS_MCP_TOOLS_DENY>" -e "PAPERLESS_MCP_AUTH_MODE=<your PAPERLESS_MCP_AUTH_MODE>" -e "PAPERLESS_MCP_BEARER_TOKENS_FILE=<your PAPERLESS_MCP_BEARER_TOKENS_FILE>" -e "PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT=<your PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT>" -e "PAPERLESS_MCP_SERVER_NAME=<your PAPERLESS_MCP_SERVER_NAME>" -e "PAPERLESS_MCP_INSTANCE_DESCRIPTION=<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>" -e "PAPERLESS_MCP_INSTRUCTIONS_EXTRA=<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>" -e "PAPERLESS_MCP_INSTRUCTIONS=<your PAPERLESS_MCP_INSTRUCTIONS>" -e "PAPERLESS_MCP_HTTP_PATH=<your PAPERLESS_MCP_HTTP_PATH>" -e "PAPERLESS_MCP_HEALTH_DETAIL=<your PAPERLESS_MCP_HEALTH_DETAIL>" -e "PUID=<your PUID>" -e "PGID=<your PGID>" -e "PAPERLESS_MCP_LOG_LEVEL=<your PAPERLESS_MCP_LOG_LEVEL>" -e "PAPERLESS_MCP_LOG_FORMAT=<your PAPERLESS_MCP_LOG_FORMAT>" -e "PAPERLESS_MCP_PAPERLESS_URL=<your PAPERLESS_MCP_PAPERLESS_URL>" -e "PAPERLESS_MCP_API_TOKEN=<your PAPERLESS_MCP_API_TOKEN>" -e "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS=<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>" -e "PAPERLESS_MCP_HTTP_RETRIES=<your PAPERLESS_MCP_HTTP_RETRIES>" -e "PAPERLESS_MCP_DEFAULT_PAGE_SIZE=<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>" -e "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL=<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>" -e "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S=<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>" -e "PAPERLESS_MCP_TRANSFER_TTL_MAX_S=<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>" -e "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S=<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>" -e "PAPERLESS_MCP_TRANSFER_LEASE_S=<your PAPERLESS_MCP_TRANSFER_LEASE_S>" -e "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES=<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>" -- docker run -i --rm ghcr.io/pvliesdonk/paperless-mcp:v3.0.0 --port 8000

Replace each placeholder with your own value before saving.

Python package (PyPI)

[mcp_servers.paperless-mcp]
command = "uvx"
args = ["pvliesdonk-paperless-mcp"]

[mcp_servers.paperless-mcp.env]
PAPERLESS_MCP_KV_STORE_URL = "<your PAPERLESS_MCP_KV_STORE_URL>"
PAPERLESS_MCP_TOOLS_ALLOW = "<your PAPERLESS_MCP_TOOLS_ALLOW>"
PAPERLESS_MCP_TOOLS_DENY = "<your PAPERLESS_MCP_TOOLS_DENY>"
PAPERLESS_MCP_SERVER_NAME = "<your PAPERLESS_MCP_SERVER_NAME>"
PAPERLESS_MCP_INSTANCE_DESCRIPTION = "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>"
PAPERLESS_MCP_INSTRUCTIONS_EXTRA = "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>"
PAPERLESS_MCP_INSTRUCTIONS = "<your PAPERLESS_MCP_INSTRUCTIONS>"
PAPERLESS_MCP_LOG_LEVEL = "<your PAPERLESS_MCP_LOG_LEVEL>"
PAPERLESS_MCP_LOG_FORMAT = "<your PAPERLESS_MCP_LOG_FORMAT>"
PAPERLESS_MCP_PAPERLESS_URL = "<your PAPERLESS_MCP_PAPERLESS_URL>"
PAPERLESS_MCP_API_TOKEN = "<your PAPERLESS_MCP_API_TOKEN>"
PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS = "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>"
PAPERLESS_MCP_HTTP_RETRIES = "<your PAPERLESS_MCP_HTTP_RETRIES>"
PAPERLESS_MCP_DEFAULT_PAGE_SIZE = "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>"
PAPERLESS_MCP_PAPERLESS_PUBLIC_URL = "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>"
PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S = "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>"
PAPERLESS_MCP_TRANSFER_TTL_MAX_S = "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>"
PAPERLESS_MCP_TRANSFER_GRACE_TTL_S = "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>"
PAPERLESS_MCP_TRANSFER_LEASE_S = "<your PAPERLESS_MCP_TRANSFER_LEASE_S>"
PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES = "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"

Add to ~/.codex/config.toml. Replace each placeholder with your own value before saving.

Docker image

[mcp_servers.paperless-mcp]
command = "docker"
args = ["run", "-i", "--rm", "ghcr.io/pvliesdonk/paperless-mcp:v3.0.0", "--port", "8000"]

[mcp_servers.paperless-mcp.env]
PAPERLESS_MCP_SHUTDOWN_GRACE_S = "<your PAPERLESS_MCP_SHUTDOWN_GRACE_S>"
PAPERLESS_MCP_BASE_URL = "<your PAPERLESS_MCP_BASE_URL>"
PAPERLESS_MCP_BEARER_TOKEN = "<your PAPERLESS_MCP_BEARER_TOKEN>"
PAPERLESS_MCP_OIDC_CONFIG_URL = "<your PAPERLESS_MCP_OIDC_CONFIG_URL>"
PAPERLESS_MCP_OIDC_CLIENT_ID = "<your PAPERLESS_MCP_OIDC_CLIENT_ID>"
PAPERLESS_MCP_OIDC_CLIENT_SECRET = "<your PAPERLESS_MCP_OIDC_CLIENT_SECRET>"
PAPERLESS_MCP_OIDC_AUDIENCE = "<your PAPERLESS_MCP_OIDC_AUDIENCE>"
PAPERLESS_MCP_OIDC_REQUIRED_SCOPES = "<your PAPERLESS_MCP_OIDC_REQUIRED_SCOPES>"
PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES = "<your PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES>"
PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY = "<your PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY>"
PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN = "<your PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN>"
PAPERLESS_MCP_KV_STORE_URL = "<your PAPERLESS_MCP_KV_STORE_URL>"
PAPERLESS_MCP_APP_DOMAIN = "<your PAPERLESS_MCP_APP_DOMAIN>"
PAPERLESS_MCP_TOOLS_ALLOW = "<your PAPERLESS_MCP_TOOLS_ALLOW>"
PAPERLESS_MCP_TOOLS_DENY = "<your PAPERLESS_MCP_TOOLS_DENY>"
PAPERLESS_MCP_AUTH_MODE = "<your PAPERLESS_MCP_AUTH_MODE>"
PAPERLESS_MCP_BEARER_TOKENS_FILE = "<your PAPERLESS_MCP_BEARER_TOKENS_FILE>"
PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT = "<your PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT>"
PAPERLESS_MCP_SERVER_NAME = "<your PAPERLESS_MCP_SERVER_NAME>"
PAPERLESS_MCP_INSTANCE_DESCRIPTION = "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>"
PAPERLESS_MCP_INSTRUCTIONS_EXTRA = "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>"
PAPERLESS_MCP_INSTRUCTIONS = "<your PAPERLESS_MCP_INSTRUCTIONS>"
PAPERLESS_MCP_HTTP_PATH = "<your PAPERLESS_MCP_HTTP_PATH>"
PAPERLESS_MCP_HEALTH_DETAIL = "<your PAPERLESS_MCP_HEALTH_DETAIL>"
PUID = "<your PUID>"
PGID = "<your PGID>"
PAPERLESS_MCP_LOG_LEVEL = "<your PAPERLESS_MCP_LOG_LEVEL>"
PAPERLESS_MCP_LOG_FORMAT = "<your PAPERLESS_MCP_LOG_FORMAT>"
PAPERLESS_MCP_PAPERLESS_URL = "<your PAPERLESS_MCP_PAPERLESS_URL>"
PAPERLESS_MCP_API_TOKEN = "<your PAPERLESS_MCP_API_TOKEN>"
PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS = "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>"
PAPERLESS_MCP_HTTP_RETRIES = "<your PAPERLESS_MCP_HTTP_RETRIES>"
PAPERLESS_MCP_DEFAULT_PAGE_SIZE = "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>"
PAPERLESS_MCP_PAPERLESS_PUBLIC_URL = "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>"
PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S = "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>"
PAPERLESS_MCP_TRANSFER_TTL_MAX_S = "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>"
PAPERLESS_MCP_TRANSFER_GRACE_TTL_S = "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>"
PAPERLESS_MCP_TRANSFER_LEASE_S = "<your PAPERLESS_MCP_TRANSFER_LEASE_S>"
PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES = "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"

Add to ~/.codex/config.toml. Replace each placeholder with your own value before saving.

Python package (PyPI)

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Add to claude_desktop_config.json (Settings → Developer → Edit Config). Replace each placeholder with your own value before saving.

Docker image

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pvliesdonk/paperless-mcp:v3.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "PAPERLESS_MCP_SHUTDOWN_GRACE_S": "<your PAPERLESS_MCP_SHUTDOWN_GRACE_S>",
        "PAPERLESS_MCP_BASE_URL": "<your PAPERLESS_MCP_BASE_URL>",
        "PAPERLESS_MCP_BEARER_TOKEN": "<your PAPERLESS_MCP_BEARER_TOKEN>",
        "PAPERLESS_MCP_OIDC_CONFIG_URL": "<your PAPERLESS_MCP_OIDC_CONFIG_URL>",
        "PAPERLESS_MCP_OIDC_CLIENT_ID": "<your PAPERLESS_MCP_OIDC_CLIENT_ID>",
        "PAPERLESS_MCP_OIDC_CLIENT_SECRET": "<your PAPERLESS_MCP_OIDC_CLIENT_SECRET>",
        "PAPERLESS_MCP_OIDC_AUDIENCE": "<your PAPERLESS_MCP_OIDC_AUDIENCE>",
        "PAPERLESS_MCP_OIDC_REQUIRED_SCOPES": "<your PAPERLESS_MCP_OIDC_REQUIRED_SCOPES>",
        "PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES": "<your PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES>",
        "PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY": "<your PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY>",
        "PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN": "<your PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN>",
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_APP_DOMAIN": "<your PAPERLESS_MCP_APP_DOMAIN>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_AUTH_MODE": "<your PAPERLESS_MCP_AUTH_MODE>",
        "PAPERLESS_MCP_BEARER_TOKENS_FILE": "<your PAPERLESS_MCP_BEARER_TOKENS_FILE>",
        "PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT": "<your PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_HTTP_PATH": "<your PAPERLESS_MCP_HTTP_PATH>",
        "PAPERLESS_MCP_HEALTH_DETAIL": "<your PAPERLESS_MCP_HEALTH_DETAIL>",
        "PUID": "<your PUID>",
        "PGID": "<your PGID>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Add to claude_desktop_config.json (Settings → Developer → Edit Config). Replace each placeholder with your own value before saving.

Python package (PyPI)

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Replace each placeholder with your own value before saving.

Docker image

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pvliesdonk/paperless-mcp:v3.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "PAPERLESS_MCP_SHUTDOWN_GRACE_S": "<your PAPERLESS_MCP_SHUTDOWN_GRACE_S>",
        "PAPERLESS_MCP_BASE_URL": "<your PAPERLESS_MCP_BASE_URL>",
        "PAPERLESS_MCP_BEARER_TOKEN": "<your PAPERLESS_MCP_BEARER_TOKEN>",
        "PAPERLESS_MCP_OIDC_CONFIG_URL": "<your PAPERLESS_MCP_OIDC_CONFIG_URL>",
        "PAPERLESS_MCP_OIDC_CLIENT_ID": "<your PAPERLESS_MCP_OIDC_CLIENT_ID>",
        "PAPERLESS_MCP_OIDC_CLIENT_SECRET": "<your PAPERLESS_MCP_OIDC_CLIENT_SECRET>",
        "PAPERLESS_MCP_OIDC_AUDIENCE": "<your PAPERLESS_MCP_OIDC_AUDIENCE>",
        "PAPERLESS_MCP_OIDC_REQUIRED_SCOPES": "<your PAPERLESS_MCP_OIDC_REQUIRED_SCOPES>",
        "PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES": "<your PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES>",
        "PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY": "<your PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY>",
        "PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN": "<your PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN>",
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_APP_DOMAIN": "<your PAPERLESS_MCP_APP_DOMAIN>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_AUTH_MODE": "<your PAPERLESS_MCP_AUTH_MODE>",
        "PAPERLESS_MCP_BEARER_TOKENS_FILE": "<your PAPERLESS_MCP_BEARER_TOKENS_FILE>",
        "PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT": "<your PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_HTTP_PATH": "<your PAPERLESS_MCP_HTTP_PATH>",
        "PAPERLESS_MCP_HEALTH_DETAIL": "<your PAPERLESS_MCP_HEALTH_DETAIL>",
        "PUID": "<your PUID>",
        "PGID": "<your PGID>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Replace each placeholder with your own value before saving.

Python package (PyPI)

{
  "servers": {
    "paperless-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Save as .vscode/mcp.json in your workspace. Replace each placeholder with your own value before saving.

Docker image

{
  "servers": {
    "paperless-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pvliesdonk/paperless-mcp:v3.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "PAPERLESS_MCP_SHUTDOWN_GRACE_S": "<your PAPERLESS_MCP_SHUTDOWN_GRACE_S>",
        "PAPERLESS_MCP_BASE_URL": "<your PAPERLESS_MCP_BASE_URL>",
        "PAPERLESS_MCP_BEARER_TOKEN": "<your PAPERLESS_MCP_BEARER_TOKEN>",
        "PAPERLESS_MCP_OIDC_CONFIG_URL": "<your PAPERLESS_MCP_OIDC_CONFIG_URL>",
        "PAPERLESS_MCP_OIDC_CLIENT_ID": "<your PAPERLESS_MCP_OIDC_CLIENT_ID>",
        "PAPERLESS_MCP_OIDC_CLIENT_SECRET": "<your PAPERLESS_MCP_OIDC_CLIENT_SECRET>",
        "PAPERLESS_MCP_OIDC_AUDIENCE": "<your PAPERLESS_MCP_OIDC_AUDIENCE>",
        "PAPERLESS_MCP_OIDC_REQUIRED_SCOPES": "<your PAPERLESS_MCP_OIDC_REQUIRED_SCOPES>",
        "PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES": "<your PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES>",
        "PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY": "<your PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY>",
        "PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN": "<your PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN>",
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_APP_DOMAIN": "<your PAPERLESS_MCP_APP_DOMAIN>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_AUTH_MODE": "<your PAPERLESS_MCP_AUTH_MODE>",
        "PAPERLESS_MCP_BEARER_TOKENS_FILE": "<your PAPERLESS_MCP_BEARER_TOKENS_FILE>",
        "PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT": "<your PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_HTTP_PATH": "<your PAPERLESS_MCP_HTTP_PATH>",
        "PAPERLESS_MCP_HEALTH_DETAIL": "<your PAPERLESS_MCP_HEALTH_DETAIL>",
        "PUID": "<your PUID>",
        "PGID": "<your PGID>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Save as .vscode/mcp.json in your workspace. Replace each placeholder with your own value before saving.

Python package (PyPI)

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json. Replace each placeholder with your own value before saving.

Docker image

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pvliesdonk/paperless-mcp:v3.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "PAPERLESS_MCP_SHUTDOWN_GRACE_S": "<your PAPERLESS_MCP_SHUTDOWN_GRACE_S>",
        "PAPERLESS_MCP_BASE_URL": "<your PAPERLESS_MCP_BASE_URL>",
        "PAPERLESS_MCP_BEARER_TOKEN": "<your PAPERLESS_MCP_BEARER_TOKEN>",
        "PAPERLESS_MCP_OIDC_CONFIG_URL": "<your PAPERLESS_MCP_OIDC_CONFIG_URL>",
        "PAPERLESS_MCP_OIDC_CLIENT_ID": "<your PAPERLESS_MCP_OIDC_CLIENT_ID>",
        "PAPERLESS_MCP_OIDC_CLIENT_SECRET": "<your PAPERLESS_MCP_OIDC_CLIENT_SECRET>",
        "PAPERLESS_MCP_OIDC_AUDIENCE": "<your PAPERLESS_MCP_OIDC_AUDIENCE>",
        "PAPERLESS_MCP_OIDC_REQUIRED_SCOPES": "<your PAPERLESS_MCP_OIDC_REQUIRED_SCOPES>",
        "PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES": "<your PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES>",
        "PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY": "<your PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY>",
        "PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN": "<your PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN>",
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_APP_DOMAIN": "<your PAPERLESS_MCP_APP_DOMAIN>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_AUTH_MODE": "<your PAPERLESS_MCP_AUTH_MODE>",
        "PAPERLESS_MCP_BEARER_TOKENS_FILE": "<your PAPERLESS_MCP_BEARER_TOKENS_FILE>",
        "PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT": "<your PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_HTTP_PATH": "<your PAPERLESS_MCP_HTTP_PATH>",
        "PAPERLESS_MCP_HEALTH_DETAIL": "<your PAPERLESS_MCP_HEALTH_DETAIL>",
        "PUID": "<your PUID>",
        "PGID": "<your PGID>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json. Replace each placeholder with your own value before saving.

Python package (PyPI)

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "uvx",
      "args": [
        "pvliesdonk-paperless-mcp"
      ],
      "env": {
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Replace each placeholder with your own value before saving.

Docker image

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pvliesdonk/paperless-mcp:v3.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "PAPERLESS_MCP_SHUTDOWN_GRACE_S": "<your PAPERLESS_MCP_SHUTDOWN_GRACE_S>",
        "PAPERLESS_MCP_BASE_URL": "<your PAPERLESS_MCP_BASE_URL>",
        "PAPERLESS_MCP_BEARER_TOKEN": "<your PAPERLESS_MCP_BEARER_TOKEN>",
        "PAPERLESS_MCP_OIDC_CONFIG_URL": "<your PAPERLESS_MCP_OIDC_CONFIG_URL>",
        "PAPERLESS_MCP_OIDC_CLIENT_ID": "<your PAPERLESS_MCP_OIDC_CLIENT_ID>",
        "PAPERLESS_MCP_OIDC_CLIENT_SECRET": "<your PAPERLESS_MCP_OIDC_CLIENT_SECRET>",
        "PAPERLESS_MCP_OIDC_AUDIENCE": "<your PAPERLESS_MCP_OIDC_AUDIENCE>",
        "PAPERLESS_MCP_OIDC_REQUIRED_SCOPES": "<your PAPERLESS_MCP_OIDC_REQUIRED_SCOPES>",
        "PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES": "<your PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES>",
        "PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY": "<your PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY>",
        "PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN": "<your PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN>",
        "PAPERLESS_MCP_KV_STORE_URL": "<your PAPERLESS_MCP_KV_STORE_URL>",
        "PAPERLESS_MCP_APP_DOMAIN": "<your PAPERLESS_MCP_APP_DOMAIN>",
        "PAPERLESS_MCP_TOOLS_ALLOW": "<your PAPERLESS_MCP_TOOLS_ALLOW>",
        "PAPERLESS_MCP_TOOLS_DENY": "<your PAPERLESS_MCP_TOOLS_DENY>",
        "PAPERLESS_MCP_AUTH_MODE": "<your PAPERLESS_MCP_AUTH_MODE>",
        "PAPERLESS_MCP_BEARER_TOKENS_FILE": "<your PAPERLESS_MCP_BEARER_TOKENS_FILE>",
        "PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT": "<your PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT>",
        "PAPERLESS_MCP_SERVER_NAME": "<your PAPERLESS_MCP_SERVER_NAME>",
        "PAPERLESS_MCP_INSTANCE_DESCRIPTION": "<your PAPERLESS_MCP_INSTANCE_DESCRIPTION>",
        "PAPERLESS_MCP_INSTRUCTIONS_EXTRA": "<your PAPERLESS_MCP_INSTRUCTIONS_EXTRA>",
        "PAPERLESS_MCP_INSTRUCTIONS": "<your PAPERLESS_MCP_INSTRUCTIONS>",
        "PAPERLESS_MCP_HTTP_PATH": "<your PAPERLESS_MCP_HTTP_PATH>",
        "PAPERLESS_MCP_HEALTH_DETAIL": "<your PAPERLESS_MCP_HEALTH_DETAIL>",
        "PUID": "<your PUID>",
        "PGID": "<your PGID>",
        "PAPERLESS_MCP_LOG_LEVEL": "<your PAPERLESS_MCP_LOG_LEVEL>",
        "PAPERLESS_MCP_LOG_FORMAT": "<your PAPERLESS_MCP_LOG_FORMAT>",
        "PAPERLESS_MCP_PAPERLESS_URL": "<your PAPERLESS_MCP_PAPERLESS_URL>",
        "PAPERLESS_MCP_API_TOKEN": "<your PAPERLESS_MCP_API_TOKEN>",
        "PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS": "<your PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS>",
        "PAPERLESS_MCP_HTTP_RETRIES": "<your PAPERLESS_MCP_HTTP_RETRIES>",
        "PAPERLESS_MCP_DEFAULT_PAGE_SIZE": "<your PAPERLESS_MCP_DEFAULT_PAGE_SIZE>",
        "PAPERLESS_MCP_PAPERLESS_PUBLIC_URL": "<your PAPERLESS_MCP_PAPERLESS_PUBLIC_URL>",
        "PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S": "<your PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S>",
        "PAPERLESS_MCP_TRANSFER_TTL_MAX_S": "<your PAPERLESS_MCP_TRANSFER_TTL_MAX_S>",
        "PAPERLESS_MCP_TRANSFER_GRACE_TTL_S": "<your PAPERLESS_MCP_TRANSFER_GRACE_TTL_S>",
        "PAPERLESS_MCP_TRANSFER_LEASE_S": "<your PAPERLESS_MCP_TRANSFER_LEASE_S>",
        "PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<your PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES>"
      }
    }
  }
}

Replace each placeholder with your own value before saving.

First successful task

After adding the config, ask your client to list this server's tools. A tool list confirms the connection; an empty list or an error means the server did not start or needs credentials.

ALTERNATIVES

When to choose another server

Other servers by pvliesdonk

View all pvliesdonk servers →

No task-specific alternatives are catalogued for Paperless MCPyet; the list above is its publisher's other servers.

MAINTENANCE AND EVIDENCE

What changed, and when this was checked

First listed: Apr 24, 2026
Latest version published: Sep 21, 2026
Version history: 3 versions tracked (below)
Requirements evidence: Declared by the Official MCP Registry, last synced Oct 16, 2026. Not independently verified by MCP Toplist.
Profile checked: Not yet — purpose, capabilities and requirements above come from registry data only
Ranking data as of: Oct 16, 2026

Registry sightings

Glama ↗listed since Jun 4, 2026 · still listed
Official MCP ↗listed since Sep 17, 2026 · still listed

Do you maintain Paperless MCP? to correct or enrich this profile.

VERSIONS

Available versions (3)

Version	Published
3.0.0	Sep 21, 2026
2.1.0	Sep 19, 2026
2.0.0	Sep 17, 2026

STANDING

#9,137of 144,396 active serversTop 10%

Ranks ahead of 135,259 of 144,396 servers on MCP Toplist.

BADGE

Show your rank

Maintain this server? Add the live rank badge to your README — it updates automatically as the leaderboard changes.

Markdown

[![MCP Toplist](https://mcptoplist.com/badge/io.github.pvliesdonk%2Fpaperless-mcp.svg)](https://mcptoplist.com/server/io.github.pvliesdonk%2Fpaperless-mcp)

HTML

<a href="https://mcptoplist.com/server/io.github.pvliesdonk%2Fpaperless-mcp"><img src="https://mcptoplist.com/badge/io.github.pvliesdonk%2Fpaperless-mcp.svg" alt="MCP Toplist: Top 10% of 144,396" /></a>

Variants: append ?metric=score or ?metric=stars to the image URL.

FAQ

Frequently asked questions

Who maintains Paperless MCP?: Paperless MCP is maintained by pvliesdonk, which publishes 7 MCP servers (63 total versions) tracked on MCP Toplist.
Is Paperless MCP listed on the Official MCP Registry?: Yes — Paperless MCP is listed on the Official MCP Registry, alongside Glama.
How many versions does Paperless MCP have?: MCP Toplist tracks 3 versions of Paperless MCP, most recently published on Sep 21, 2026.
Where can I find the source code for Paperless MCP?: The source code for Paperless MCP is hosted at github.com/pvliesdonk/paperless-mcp.

Used in projects

Do you run this server?

Community projects list the MCP servers behind real agents and apps. Publish yours and this page will link to it.

EXPLORE

All MCP Servers Official MCP Servers GitHub MCP Servers Best MCP Servers Most Active MCP Servers New MCP Servers Best New MCP Servers