MCP Paperless¶

This guide enables Paperless-NGX integration through the local Dockerized Paperless MCP server registered in .mcp.json.

Scope¶

Current implementation in this repository provides:

• Docker-only MCP transport
• Pinned immutable image digest
• Secrets loaded from local .env
• Bitwarden-driven hydration of Paperless API credentials

Current image: ghcr.io/baruchiro/paperless-mcp:latest

1. Hydrate Paperless credentials from Bitwarden¶

Expected Bitwarden item:

• Item name: Paperless API
• Field PAPERLESS_URL: Paperless-NGX base URL (for example, http://paperless.local:8000)
• Field PAPERLESS_API_KEY: Paperless API token
• Optional field PAPERLESS_PUBLIC_URL: public URL for deep links

Hydrate local .env from vault fields:

just bw-paperless-api-pull

Or hydrate all supported MCP secrets in one pass:

just bw-env-hydrate

2. Validate MCP wiring¶

Run from the hermetic Nix shell:

just sync-ai
just mcp-health

Expected summary includes:

• paperless MCP docker image: ghcr.io/baruchiro/paperless-mcp@sha256:<digest>

3. Example prompts¶

In your MCP-capable client, run prompts similar to:

Use the paperless MCP server to list my latest 20 documents.

Use the paperless MCP server to search documents for "tax return".

Use the paperless MCP server to list all tags and then find documents tagged "Invoice".

Troubleshooting¶

• Usage: paperless-mcp --baseUrl ... --token ...: PAPERLESS_URL or PAPERLESS_API_KEY is missing. Re-run just bw-paperless-api-pull.
• Connection failures: verify PAPERLESS_URL points to a reachable Paperless host from Docker.
• Authentication failures: regenerate the Paperless API token and update Bitwarden item Paperless API, then re-run just bw-paperless-api-pull.