# paperless-ngx-mcp

Model Context Protocol (MCP) server for Paperless-NGX. Lets AI assistants manage documents and their versions, tags, correspondents, document types, custom fields, saved views, storage paths, workflows, mail accounts and rules, share links and bundles, no

- **Type:** MCP server
- **Trust:** 85/100 (A), scored on the package rubric
- **Verification:** verified (build provenance)
- **Version:** 3.2.1
- **Author:** Oliver Fueckert
- **License:** ISC
- **npm:** paperless-ngx-mcp
- **Source:** https://github.com/cubinet-code/paperless-ngx-mcp
- **Compatible clients:** claude-code, cursor, copilot, gemini (basis: transport)

## Trust

85/100 (A), scored on the package rubric
- Publisher verified: no
- Build provenance: verified attestation
- npm trusted publishing (OIDC): yes
- Install scripts: nothing suspicious found
- Prompt-injection scan: not run
- Obfuscation scan: not run
- Evidence age: 0 days

## Security scan

- **Status:** clean
- **Scanned:** 2026-10-01T02:06:06.249Z
- **Version scanned:** 3.2.1
- **CVEs:** none found by OSV at scan time

## Tools

40 declared. Statically extracted from the shipped source — a floor on the surface, not a census.
- `list_correspondents` — List all correspondents with optional filtering and pagination. Correspondents represent entities that send or receive documents.
- `get_correspondent` — Get a specific correspondent by ID with full details including matching rules.
- `create_correspondent` — Create a new correspondent with optional matching pattern and algorithm for automatic document assignment.
- `update_correspondent` — Update fields on ONE correspondent (PATCH — only fields you supply are changed). Editable fields: name, match (matching pattern), matching_algorithm, is_insensi
- `delete_correspondent` — ⚠️ DESTRUCTIVE: Permanently delete a correspondent from the entire system. This will affect ALL documents that use this correspondent.
- `list_custom_fields` — List all custom fields. IMPORTANT: When a user query may refer to a custom field, you should fetch all custom fields up front (with a large enough page_size), c
- `get_custom_field` — Get a specific custom field by ID with full details including data type and extra configuration.
- `create_custom_field` — Create a new custom field with a specified data type (string, url, date, boolean, integer, float, monetary, documentlink, or select). For monetary fields, value
- `update_custom_field` — Update fields on ONE custom field definition (PATCH — only fields you supply are changed). Editable fields: name, data_type, extra_data. ⚠️ Changing data_type o
- `delete_custom_field` — ⚠️ DESTRUCTIVE: Permanently delete a custom field from the entire system. This will remove the field from ALL documents that use it.
- `edit_custom_fields_bulk` — Manage custom field definitions themselves (permissions, delete). ⚠️ This does NOT modify custom field values on documents — use edit_documents_bulk with method
- `edit_documents_bulk`
- `post_document` — Upload a new document file (PDF, image, etc.) to Paperless-NGX with optional metadata. Upload is asynchronous: by default returns a task UUID (use list_tasks to
- `list_documents`
- `get_document`
- `get_document_content` — Get the text content of a specific document by ID. Use this when you need to read or analyze the actual document text. For long documents, read a slice with max
- `search_documents` — Ranked full-text search through Paperless's search index (content, title and metadata). mode 'query' (default) takes advanced syntax — AND/OR/NOT, "quoted phras
- `download_document` — Download a document file by ID. Returns the document as a base64-encoded resource.
- `get_document_thumbnail` — Get a document thumbnail (image preview) by ID. Returns the thumbnail as a base64-encoded WebP image resource.
- `update_document`
- `email_document` — Send a document via email to one or more recipients.
- `get_document_history` — Get the change history / audit log for a document, showing who changed what and when.
- `get_document_preview` — Get a full-page preview image of a document. Returns the preview as a base64-encoded image resource.
- `list_document_types` — List all document types. IMPORTANT: When a user query may refer to a document type or tag, you should fetch all document types and all tags up front (get_filing
- `get_document_type` — Get a specific document type by ID with full details including matching rules.
- `create_document_type` — Create a new document type with optional matching pattern and algorithm for automatic document classification.
- `update_document_type` — Update fields on ONE document type (PATCH — only fields you supply are changed). Editable fields: name, match (matching pattern), matching_algorithm, is_insensi
- `delete_document_type` — ⚠️ DESTRUCTIVE: Permanently delete a document type from the entire system. This will affect ALL documents that use this type.
- `upload_document_version` — Add a new file version to an EXISTING document instead of creating a new document — e.g. a corrected scan, a signed copy, or an unlocked PDF. The new file becom
- `update_document_version` — Rename a version of a document (change its version_label). Version IDs are listed in get_document's `versions`.
- `delete_document_version` — ⚠️ DESTRUCTIVE: Permanently delete one non-root version of a document. The root (original) version can't be deleted — delete the document instead.
- `merge_documents_as_versions` — ⚠️ Fold other documents into one document as its versions: each document in merge_documents stops existing as a separate document and becomes a version of root_
- `list_mail_accounts` — List the IMAP accounts Paperless fetches mail from. Passwords are always masked.
- `get_mail_account` — Get one mail account by ID (password masked).
- `create_mail_account` — Create an IMAP account for Paperless to fetch mail from. Nothing is fetched until a mail rule uses the account (create_mail_rule). Check the connection first wi
- `update_mail_account` — Update fields on ONE mail account (PATCH — only fields you supply are changed). Omit password to keep the stored one.
- `delete_mail_account` — ⚠️ DESTRUCTIVE: Permanently delete a mail account and stop fetching from it. Mail rules using it are deleted too. Already-imported documents are not affected.
- `test_mail_account`
- `process_mail_account` — Fetch mail for one account now and run its rules, instead of waiting for the schedule. Runs in the background; see list_tasks with task_type mail_fetch.
- `list_mail_rules`

## Install

**Verdict: install** — No blocking findings and no open coverage gaps — safe to install as configured.
**Config** (claude-code):
```json
"{\n  \"mcpServers\": {\n    \"paperless-ngx\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"paperless-ngx-mcp\"\n      ],\n      \"env\": {\n        \"PAPERLESS_API_KEY\": \"<YOUR_PAPERLESS_API_KEY>\"\n      }\n    }\n  }\n}"
```
**Credentials it will ask for** (names only — Forge never holds a value):
- `PAPERLESS_API_KEY` — Paperless API Key (required)
Placeholders only. Forge never holds, brokers, or transmits a credential value — replace each <YOUR_NAME> in your own config file. Do not send a value back to Forge; no Forge endpoint accepts one.
- This entry needs 1 credential (1 required). The generated config carries placeholders, so it will fail in the editor rather than at runtime if they are left unset.

## Blast radius

Extensive blast radius — deletes data; holds an api key.
- Floor 58, ceiling 58 (tier: extensive)
- This is impact, not likelihood. A high radius is not a defect: a filesystem server is supposed to write files. It is never part of the trust score.

## Machine-readable views of this entry

- Signed JSON: https://forgeregistry.com/api/v1/packages/paperless-ngx-mcp
- Install plan: https://forgeregistry.com/api/v1/packages/paperless-ngx-mcp/install-plan
- Alternatives: https://forgeregistry.com/api/v1/alternatives/paperless-ngx-mcp
- HTML page: https://forgeregistry.com/registry/paperless-ngx-mcp
- MCP: POST https://forgeregistry.com/api/mcp → `forge_get_package` / `forge_install_plan`

## About this document

Generated by Forge (https://forgeregistry.com) — a compact rendering of the same record served, signed, at the JSON URL above. Trust and scan facts are the registry's own measurements; anything Forge did not measure is named as unmeasured rather than omitted.