paperless-ngx-mcp

A Model Context Protocol server for Paperless-NGX. Exposes the full Paperless-NGX REST API to AI assistants — documents, tags, correspondents, document types, custom fields, storage paths, saved views, share links and bundles, workflows, mail accounts and rules, document versions, notes, trash, and tasks.

Why this one?

• Complete, and it stays that way. A CI test checks every endpoint in Paperless's /api/schema/ against the tools here and fails when upstream adds one that is neither wrapped nor deliberately skipped.
• Tested against real Paperless. The end-to-end suite runs the tools against a live Paperless-ngx 3.2.1 container, not mocks.
• Asks before it breaks things. Every delete_* tool, empty_trash, merge_documents_as_versions and bulk delete require confirm: true; bulk edits across "all matching documents" refuse filters Paperless would silently ignore; and the triage_inbox prompt proposes changes and waits for your go-ahead before writing anything.
• Easy to allowlist. Verb-first tool names (list_*, get_*, delete_*, …) group into one permission wildcard each.
• Install it your way: npx, a Docker image, a one-click Claude Desktop extension, or the official MCP Registry.

Compatibility

Targets Paperless-ngx 3.2 (tested against 3.2.1). Older Paperless versions are not supported — use paperless-ngx-mcp@3.1.1 for Paperless 2.x. The package major version tracks the Paperless-ngx major it targets; there are no 1.x or 2.x releases.

Quick Start

The server is published to npm as paperless-ngx-mcp. You can run it with npx — no clone or build required.

Claude Code

claude mcp add paperless --scope user \
  --env PAPERLESS_URL=https://your-paperless-instance \
  --env PAPERLESS_API_KEY=your-api-token \
  -- npx -y paperless-ngx-mcp

Drop --scope user to install for the current project only. See claude mcp add --help for more options.

Codex CLI

codex mcp add paperless \
  --env PAPERLESS_URL=https://your-paperless-instance \
  --env PAPERLESS_API_KEY=your-api-token \
  -- npx -y paperless-ngx-mcp

This writes the entry to ~/.codex/config.toml.

Claude Desktop (extension)

Download paperless-ngx-mcp.mcpb from the latest release and double-click it, or install it from Settings → Extensions. Claude Desktop asks for your Paperless URL and API token.

Claude Desktop, Cursor, Cline, and other MCP clients

The buttons install placeholder values; replace PAPERLESS_URL and PAPERLESS_API_KEY afterwards. Or add this to your client's MCP config file (e.g. claude_desktop_config.json, ~/.cursor/mcp.json, ~/.config/cline/mcp.json):

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["-y", "paperless-ngx-mcp"],
      "env": {
        "PAPERLESS_URL": "https://your-paperless-instance",
        "PAPERLESS_API_KEY": "your-api-token",
        "PAPERLESS_PUBLIC_URL": "https://your-public-domain"
      }
    }
  }
}

Docker

A multi-arch image (amd64, arm64) is published to ghcr.io/cubinet-code/paperless-ngx-mcp. As a stdio server in any MCP client config:

{
  "mcpServers": {
    "paperless": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "PAPERLESS_URL", "-e", "PAPERLESS_API_KEY", "ghcr.io/cubinet-code/paperless-ngx-mcp"],
      "env": {
        "PAPERLESS_URL": "https://your-paperless-instance",
        "PAPERLESS_API_KEY": "your-api-token"
      }
    }
  }
}

Or as a long-running Streamable HTTP server. It has no authentication, so keep it off untrusted networks:

docker run -d -p 127.0.0.1:3000:3000 \
  -e PAPERLESS_URL=https://your-paperless-instance \
  -e PAPERLESS_API_KEY=your-api-token \
  ghcr.io/cubinet-code/paperless-ngx-mcp --http --port 3000

Get your Paperless-NGX API token

1. Log into your Paperless-NGX instance.
2. Click your username (top right) → My Profile.
3. Click the circular arrow button to generate a new token.

Configuration

| Variable | Required | Purpose | |---|---|---| | PAPERLESS_URL | yes | Base URL the MCP server uses to talk to Paperless-NGX. | | PAPERLESS_API_KEY | yes | API token (see above). | | PAPERLESS_PUBLIC_URL | no | Public URL the assistant uses when constructing browser links to documents. Falls back to PAPERLESS_URL. |

CLI flags (--baseUrl, --token, --publicUrl, --http, --port, plus the HTTP session limits) take precedence over environment variables.

Example Usage

Things you can ask Claude (or any MCP-aware assistant):

• "Show me all documents tagged as 'Invoice'"
• "Search for documents containing 'tax return'"
• "Create a new tag called 'Receipts' with color #FF0000"
• "Download document #123"
• "List all correspondents"
• "Create a new document type called 'Bank Statement'"
• "Empty the trash"
• "Show me pending consumption tasks"
• "Move every document from correspondent 'ACME GmbH (mail)' to 'ACME GmbH'"
• "Remove the password from document #55 and keep the unlocked file as a new version"
• "Create a workflow that strips PDF passwords from uploaded bank statements"
• "Which mail rule is creating a new correspondent for every sender?"

Available Tools

The server registers tools across twelve domains.

Documents

list_documents, get_document, get_document_content, search_documents, download_document, download_documents_bulk, get_document_thumbnail, get_document_preview, get_document_history, get_document_metadata, update_document, post_document, email_document, edit_documents_bulk, delete_document, search_autocomplete, get_document_suggestions, get_document_ai_suggestions, get_next_asn, upload_document_version, update_document_version, delete_document_version, merge_documents_as_versions

Tags

list_tags, get_tag, create_tag, update_tag, delete_tag, edit_tags_bulk

Correspondents

list_correspondents, get_correspondent, create_correspondent, update_correspondent, delete_correspondent, edit_correspondents_bulk

Document Types

list_document_types, get_document_type, create_document_type, update_document_type, delete_document_type, edit_document_types_bulk

Custom Fields

list_custom_fields, get_custom_field, create_custom_field, update_custom_field, delete_custom_field, edit_custom_fields_bulk

Storage Paths

list_storage_paths, get_storage_path, create_storage_path, update_storage_path, delete_storage_path, test_storage_path

Saved Views

list_saved_views, get_saved_view, create_saved_view, update_saved_view, delete_saved_view

Share Links

list_share_links, list_document_share_links, get_share_link, create_share_link, delete_share_link, list_share_link_bundles, get_share_link_bundle, create_share_link_bundle, rebuild_share_link_bundle, delete_share_link_bundle

Workflows

list_workflows, get_workflow, create_workflow, update_workflow, delete_workflow, list_workflow_actions, get_workflow_action, create_workflow_action, update_workflow_action, delete_workflow_action, list_workflow_triggers, get_workflow_trigger, create_workflow_trigger, update_workflow_trigger, delete_workflow_trigger

Mail

list_mail_accounts, get_mail_account, create_mail_account, update_mail_account, delete_mail_account, test_mail_account, process_mail_account, list_mail_rules, get_mail_rule, create_mail_rule, update_mail_rule, delete_mail_rule

System / Notes / Trash / Tasks

get_statistics, get_system_status, get_filing_options, list_document_notes, create_document_note, delete_document_note, list_trash, restore_from_trash, empty_trash, list_tasks, list_active_tasks, get_task_status_counts, get_task_summary, acknowledge_tasks

Tool naming convention (for permission allowlists)

Tool names are verb-first, so wildcard-based permission rules group cleanly by operation:

| Wildcard | Covers | |---|---| | mcp__paperless__list_* | All list/index reads | | mcp__paperless__get_* | All single-item reads | | mcp__paperless__search_* | Full-text search and autocomplete | | mcp__paperless__download_* | download_document and download_documents_bulk | | mcp__paperless__create_* | All create endpoints | | mcp__paperless__update_* | Per-item PATCH updates | | mcp__paperless__edit_*_bulk | All bulk-edit operations across entity types | | mcp__paperless__delete_* | ⚠️ Destructive — system-wide deletes | | mcp__paperless__test_* | Dry-run checks: test_storage_path, test_mail_account | | mcp__paperless__upload_* | upload_document_version | | mcp__paperless__rebuild_* | rebuild_share_link_bundle | | mcp__paperless__merge_* | ⚠️ merge_documents_as_versions — merged documents stop existing on their own | | mcp__paperless__process_* | process_mail_account — fetches mail now and runs its rules (which may delete or move mail on the server) |

A read-only allowlist is therefore: list_*, get_*, search_*, download_*, test_*. Write access without destructive operations: add create_*, update_*, edit_*_bulk, upload_*, rebuild_*, post_document, email_document, restore_from_trash, acknowledge_tasks. delete_*, merge_*, process_* and empty_trash should require explicit user approval.

Prompts

The server also registers MCP prompts — reusable, parameterized instructions that surface as slash commands in clients like Claude Code (e.g. /mcp__paperless__triage_inbox).

triage_inbox

Walks the assistant through inbox triage: gather existing tags / correspondents / document types, propose metadata for each inbox document preferring existing items, present a confirmation table, and only apply changes after the user replies apply. New correspondents / types / tags are flagged (NEW) so you can veto creations before they happen.

Argument:

• limit (optional, default 25): maximum number of inbox documents to triage in one pass.

Notable tool details

edit_documents_bulk

Perform bulk operations on multiple documents.

Parameters:

• Selection: documents (array of IDs), or all: true + filters with optional excluded_documents.