Repository navigation
Releases
v0.4.0
Merge pull request #10 from Marceltov/paperless-ngx-mcp-9-mcp-login-oauth
PAPERLESS-NGX-MCP #9: Move OAuth onto mcp-login-oauth and FastMCP 4
Install
All you need is a running Paperless-ngx and Docker — no checkout, no build.
1. Add the Paperless-ngx MCP server to your Paperless-ngx docker-compose.yaml — one service, pulling the prebuilt image:
services:
webserver:
# ... your existing Paperless-ngx service ...
paperless-ngx-mcp:
image: ghcr.io/marceltov/paperless-ngx-mcp:0.4.0
container_name: paperless-ngx-mcp
restart: unless-stopped
environment:
# Service name and port of Paperless-ngx on the same compose network.
PAPERLESS_URL: http://webserver:8000
# Optional — enables OAuth login for remote/app clients:
# MCP_BASE_URL: https://paperless-ngx-mcp.example
# MCP_OAUTH_SECRET: <long random string>
# volumes:
# - mcp-oauth:/data # keeps OAuth logins across restarts
ports:
- "8081:8081"Then start it:
docker compose up -d paperless-ngx-mcpOn startup it downloads the OpenAPI spec from your Paperless-ngx (/api/schema/) and turns it into tools, so they match the version you run.
2. Connect your MCP client, pointing at wherever the Paperless-ngx MCP server is reachable:
# With an API token (Paperless-ngx: My Profile → API Auth Token)
claude mcp add paperless-ngx --scope user --transport http \
https://paperless-ngx-mcp.example/mcp \
--header "Authorization: YOUR_PAPERLESS_API_TOKEN"
# With OAuth enabled: URL only, log in once in the browser
claude mcp add paperless-ngx --scope user --transport http \
https://paperless-ngx-mcp.example/mcpFull guide: documentation
v0.3.1
Merge pull request #8 from Marceltov/release-0.3.1
Release 0.3.1
Install
All you need is a running Paperless-ngx and Docker — no checkout, no build.
1. Add the Paperless-ngx MCP server to your Paperless-ngx docker-compose.yaml — one service, pulling the prebuilt image:
services:
webserver:
# ... your existing Paperless-ngx service ...
paperless-ngx-mcp:
image: ghcr.io/marceltov/paperless-ngx-mcp:0.3.1
container_name: paperless-ngx-mcp
restart: unless-stopped
environment:
# Service name and port of Paperless-ngx on the same compose network.
PAPERLESS_URL: http://webserver:8000
# Optional — enables OAuth login for remote/app clients:
# MCP_BASE_URL: https://paperless-ngx-mcp.example
# MCP_OAUTH_SECRET: <long random string>
# volumes:
# - mcp-oauth:/data # keeps OAuth logins across restarts
ports:
- "8081:8081"Then start it:
docker compose up -d paperless-ngx-mcpOn startup it downloads the OpenAPI spec from your Paperless-ngx (/api/schema/) and turns it into tools, so they match the version you run.
2. Connect your MCP client, pointing at wherever the Paperless-ngx MCP server is reachable:
# With an API token (Paperless-ngx: My Profile → API Auth Token)
claude mcp add paperless-ngx --scope user --transport http \
https://paperless-ngx-mcp.example/mcp \
--header "Authorization: YOUR_PAPERLESS_API_TOKEN"
# With OAuth enabled: URL only, log in once in the browser
claude mcp add paperless-ngx --scope user --transport http \
https://paperless-ngx-mcp.example/mcpFull guide: documentation
v0.3.0
Merge pull request #6 from Marceltov/release-0.3.0
Release 0.3.0
Install
All you need is a running Paperless-ngx and Docker — no checkout, no build.
1. Add the Paperless-ngx MCP server to your Paperless-ngx docker-compose.yaml — one service, pulling the prebuilt image:
services:
webserver:
# ... your existing Paperless-ngx service ...
paperless-ngx-mcp:
image: ghcr.io/marceltov/paperless-ngx-mcp:0.3.0
container_name: paperless-ngx-mcp
restart: unless-stopped
environment:
# Service name and port of Paperless-ngx on the same compose network.
PAPERLESS_URL: http://webserver:8000
# Optional — enables OAuth login for remote/app clients:
# MCP_BASE_URL: https://paperless-ngx-mcp.example
# MCP_OAUTH_SECRET: <long random string>
# volumes:
# - mcp-oauth:/data # keeps OAuth logins across restarts
ports:
- "8081:8081"Then start it:
docker compose up -d paperless-ngx-mcpOn startup it downloads the OpenAPI spec from your Paperless-ngx (/api/schema/) and turns it into tools, so they match the version you run.
2. Connect your MCP client, pointing at wherever the Paperless-ngx MCP server is reachable:
# With an API token (Paperless-ngx: My Profile → API Auth Token)
claude mcp add paperless-ngx --scope user --transport http \
https://paperless-ngx-mcp.example/mcp \
--header "Authorization: YOUR_PAPERLESS_API_TOKEN"
# With OAuth enabled: URL only, log in once in the browser
claude mcp add paperless-ngx --scope user --transport http \
https://paperless-ngx-mcp.example/mcpFull guide: documentation
v0.2.0
Merge pull request #4 from Marceltov/release-0.2.0
Release 0.2.0
Install
All you need is a running Paperless-ngx and Docker — no checkout, no build.
1. Add the Paperless-ngx MCP server to your Paperless-ngx docker-compose.yaml — one service, pulling the prebuilt image:
services:
webserver:
# ... your existing Paperless-ngx service ...
paperless-ngx-mcp:
image: ghcr.io/marceltov/paperless-ngx-mcp:0.2.0
container_name: paperless-ngx-mcp
restart: unless-stopped
environment:
# Service name and port of Paperless-ngx on the same compose network.
PAPERLESS_URL: http://webserver:8000
# Optional — enables OAuth login for remote/app clients:
# MCP_BASE_URL: https://paperless-ngx-mcp.example
# MCP_OAUTH_SECRET: <long random string>
# volumes:
# - mcp-oauth:/data # keeps OAuth logins across restarts
ports:
- "8081:8081"Then start it:
docker compose up -d paperless-ngx-mcpOn startup it downloads the OpenAPI spec from your Paperless-ngx (/api/schema/) and turns it into tools, so they match the version you run.
2. Connect your MCP client, pointing at wherever the Paperless-ngx MCP server is reachable:
# With an API token (Paperless-ngx: My Profile → API Auth Token)
claude mcp add paperless-ngx --scope user --transport http \
https://paperless-ngx-mcp.example/mcp \
--header "Authorization: YOUR_PAPERLESS_API_TOKEN"
# With OAuth enabled: URL only, log in once in the browser
claude mcp add paperless-ngx --scope user --transport http \
https://paperless-ngx-mcp.example/mcpFull guide: documentation
v0.1.1
Add behaviour hints, written descriptions and server instructions (#2)
Every tool now carries MCP annotations (read-only, destructive,
idempotent, open-world), derived from its HTTP method with the POST
exceptions listed by operation ID. The most used and the most dangerous
tools get hand-written descriptions that say what comes back and how to
keep the result small; boilerplate spec text is replaced by a plain
sentence, and lists and deletes get a note. The server sends
instructions on connect.
Claude-Session: https://claude.ai/code/session_01EXt3HMRvEevqjQE4ZgTa7t
Co-authored-by: Claude Opus 5.5 noreply@anthropic.com
Install
All you need is a running Paperless-ngx and Docker — no checkout, no build.
1. Add paperless-mcp to your Paperless-ngx docker-compose.yaml — one service, pulling the prebuilt image:
services:
webserver:
# ... your existing Paperless-ngx service ...
paperless-mcp:
image: ghcr.io/marceltov/paperless-mcp:0.1.1
container_name: paperless-mcp
restart: unless-stopped
environment:
# Service name and port of Paperless-ngx on the same compose network.
PAPERLESS_URL: http://webserver:8000
# Optional — enables OAuth login for remote/app clients:
# MCP_BASE_URL: https://paperless-mcp.example
# MCP_OAUTH_SECRET: <long random string>
# volumes:
# - mcp-oauth:/data # keeps OAuth logins across restarts
ports:
- "8081:8081"Then start it:
docker compose up -d paperless-mcpOn startup it downloads the OpenAPI spec from your Paperless-ngx (/api/schema/) and turns it into tools, so they match the version you run.
2. Connect your MCP client, pointing at wherever paperless-mcp is reachable:
# With an API token (Paperless-ngx: My Profile → API Auth Token)
claude mcp add paperless --scope user --transport http \
https://paperless-mcp.example/mcp \
--header "Authorization: YOUR_PAPERLESS_API_TOKEN"
# With OAuth enabled: URL only, log in once in the browser
claude mcp add paperless --scope user --transport http \
https://paperless-mcp.example/mcpFull guide: documentation
v0.1.0
Track the separate-project .env.example (#1)
The .env.* ignore rule also matched examples/separate-project/.env.example,
so it was never committed and the docs build failed on the missing snippet.
Claude-Session: https://claude.ai/code/session_01EXt3HMRvEevqjQE4ZgTa7t
Co-authored-by: Claude Opus 5.5 noreply@anthropic.com
Install
All you need is a running Paperless-ngx and Docker — no checkout, no build.
1. Add paperless-mcp to your Paperless-ngx docker-compose.yaml — one service, pulling the prebuilt image:
services:
webserver:
# ... your existing Paperless-ngx service ...
paperless-mcp:
image: ghcr.io/marceltov/paperless-mcp:0.1.0
container_name: paperless-mcp
restart: unless-stopped
environment:
# Service name and port of Paperless-ngx on the same compose network.
PAPERLESS_URL: http://webserver:8000
# Optional — enables OAuth login for remote/app clients:
# MCP_BASE_URL: https://paperless-mcp.example
# MCP_OAUTH_SECRET: <long random string>
# volumes:
# - mcp-oauth:/data # keeps OAuth logins across restarts
ports:
- "8081:8081"Then start it:
docker compose up -d paperless-mcpOn startup it downloads the OpenAPI spec from your Paperless-ngx (/api/schema/) and turns it into tools, so they match the version you run.
2. Connect your MCP client, pointing at wherever paperless-mcp is reachable:
# With an API token (Paperless-ngx: My Profile → API Auth Token)
claude mcp add paperless --scope user --transport http \
https://paperless-mcp.example/mcp \
--header "Authorization: YOUR_PAPERLESS_API_TOKEN"
# With OAuth enabled: URL only, log in once in the browser
claude mcp add paperless --scope user --transport http \
https://paperless-mcp.example/mcpFull guide: documentation