Atlas / MCP servers / baruchiro / Paperless NGX

Paperless NGXSAFE

Name: Paperless NGX
Author: baruchiro

mcp/baruchiro/paperless-ngx-1

MCP server by baruchiro · ai · document management · mcp · Audited 2026-10-07

An MCP (Model Context Protocol) server for interacting with a Paperless-NGX API server. This server provides tools for managing documents, tags, correspondents, and document types in your Paperless-NGX instance.

Verdict

SAFE

Grade

Trust score

89 /100

Exposed tools

44 19r · 19w · 6d

Transport

sse · stdio · streamable-http

License

ISC

Stars

146

Overview

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

Quick Start

[](https://cursor.com/install-mcp?name=paperless&config=eyJjb21tYW5kIjoibnB4IC15IEBiYXJ1Y2hpcm8vcGFwZXJsZXNzLW1jcEBsYXRlc3QiLCJlbnYiOnsiUEFQRVJMRVNTX1VSTCI6Imh0dHA6Ly95b3VyLXBhcGVybGVzcy1pbnN0YW5jZTo4MDAwIiwiUEFQRVJMRVNTX0FQSV9LRVkiOiJ5b3VyLWFwaS10b2tlbiJ9fQ%3D%3D)

Installation

Add these to your MCP config file:

// STDIO mode (recommended for local or CLI use)

"paperless": {
"command": "npx",
"args": [
"-y",
"@baruchiro/paperless-mcp@latest",
],
"env": {
"PAPERLESS_URL": "http://your-paperless-instance:8000",
"PAPERLESS_API_KEY": "your-api-token",
"PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
}
}

// HTTP mode (recommended for Docker or remote use)

"paperless": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/baruchiro/paperless-mcp:latest",
],
"env": {
"PAPERLESS_URL": "http://your-paperless-instance:8000",
"PAPERLESS_API_KEY": "your-api-token",
"PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
}
}

Get your API token:
Log into your Paperless-NGX instance
Click your username in the top right
Select "My Profile"
Click the circular arrow button to generate a new token

Replace the pl

Read from source at commit 112a4d9f157dOBSERVED · 2026-10-07

Connect

Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.

claude-code

claude mcp add paperless-mcp --env PAPERLESS_API_KEY=${PAPERLESS_API_KEY} --env PAPERLESS_TOKEN=${PAPERLESS_TOKEN} -- npx -y @baruchiro/[email protected]

claude-desktop

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@baruchiro/[email protected]"
      ],
      "env": {
        "PAPERLESS_API_KEY": "${PAPERLESS_API_KEY}",
        "PAPERLESS_TOKEN": "${PAPERLESS_TOKEN}"
      }
    }
  }
}

Exposed tools (44)

19 read · 19 write · 6 destructive. Blast radius: 6 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.

Tool	Risk	Description
`bulk_edit_correspondents`	write	Bulk edit correspondents. ⚠️ WARNING:
`bulk_edit_custom_fields`	write	Bulk edit custom fields. ⚠️ WARNING:
`bulk_edit_document_types`	write	Bulk edit document types. ⚠️ WARNING:
`bulk_edit_documents`	write	Perform bulk operations on multiple documents. Note:
`bulk_edit_tags`	write	Bulk edit tags. ⚠️ WARNING:
`create_correspondent`	write	Create a new correspondent with optional matching pattern and algorithm for automatic document assignment.
`create_custom_field`	write	Create a new custom field with a specified data type (string, url, date, boolean, integer, float, monetary, documentlink, or select). For monetary fields, values must use currency code prefix format (e.g., USD10.00, GBP123.45) — NOT trailing symbol format (e.g., 10.00$).
`create_document_note`	write	Add a note to a document. Use this to record an audit trail or progress note directly on the document. Returns the document
`create_document_type`	write	Create a new document type with optional matching pattern and algorithm for automatic document classification.
`create_mail_rule`	write	Create a Paperless mail rule. Use list_mail_accounts first to choose account. Prefer attachment-only rules for invoices unless the full mail must be archived.
`create_tag`	write	Create a new tag with optional color, matching pattern, and matching algorithm for automatic document tagging.
`delete_correspondent`	destructive	⚠️ DESTRUCTIVE: Permanently delete a correspondent from the entire system. This will affect ALL documents that use this correspondent.
`delete_custom_field`	destructive	⚠️ DESTRUCTIVE: Permanently delete a custom field from the entire system. This will remove the field from ALL documents that use it.
`delete_document_note`	destructive	⚠️ DESTRUCTIVE: Permanently delete a single note from a document by its note ID. This operation is irreversible. Returns the document
`delete_document_type`	destructive	⚠️ DESTRUCTIVE: Permanently delete a document type from the entire system. This will affect ALL documents that use this type.
`delete_mail_rule`	destructive	Delete one Paperless mail rule. This changes future mail ingestion behavior but does not delete documents.
`delete_tag`	destructive	⚠️ DESTRUCTIVE: Permanently delete a tag from the entire system. This will remove the tag from ALL documents that use it. Use with extreme caution.
`download_document`	read	Download a document file by ID. Returns a paperless:// resource URI; read the resource to fetch the file content.
`get_correspondent`	read	Get a specific correspondent by ID with full details including matching rules.
`get_custom_field`	read	Get a specific custom field by ID with full details including data type and extra configuration.
`get_document`	read	Get a specific document by ID with full details including correspondent, document type, tags, and custom fields. Note: Document content is excluded from results by default. Use
`get_document_content`	read	Get the text content of a specific document by ID. Use this when you need to read or analyze the actual document text.
`get_document_thumbnail`	read	Get a document thumbnail (image preview) by ID. Returns a paperless:// resource URI; read the resource to fetch the image content.
`get_document_type`	read	Get a specific document type by ID with full details including matching rules.
`get_mail_account`	read	Get one Paperless mail account by ID. Password/token fields are redacted if the server returns them.
`get_mail_rule`	read	Get one Paperless mail rule by ID.
`list_correspondents`	read	List all correspondents with optional filtering and pagination. Correspondents represent entities that send or receive documents.
`list_custom_fields`	read
`list_document_notes`	read	List all notes attached to a document. Notes are free-text comments on a document and are the natural place for an audit trail (e.g. \
`list_document_types`	read
`list_documents`	read	List and filter documents with pagination and common Paperless filters such as title search, correspondent, document type, tag, storage path, creation date, archive serial number, and simple custom field filters. Use
`list_mail_accounts`	read	List Paperless mail accounts for selecting the account ID needed by mail rules. Does not expose account passwords.
`list_mail_rules`	read	List Paperless mail rules with optional pagination.
`list_tags`	read
`post_document`	write	Upload a new document to Paperless-NGX with optional metadata like title, correspondent, document type, tags, and custom fields. Provide either
`process_mail_account`	write	Manually run Paperless mail processing for one account. This can consume matching mails according to enabled Paperless mail rules.
`query_documents`	read
`search_documents`	read	Deprecated compatibility wrapper for full-text document search. Use
`update_correspondent`	write	Update an existing correspondent
`update_custom_field`	write	Update an existing custom field
`update_document`	write	Update a specific document with new values (title, correspondent, document type, storage path, tags, custom fields, and more). Top-level fields you omit are left unchanged. IMPORTANT: custom_fields is the exception — see its parameter description; it replaces the document
`update_document_type`	write	Update an existing document type
`update_mail_rule`	write	Patch an existing Paperless mail rule. Only supplied fields are changed.
`update_tag`	write	Update an existing tag

Trust audit

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

Layer	What it checks	Result
L0	Provenance & inventory	PASS
L1	Static analysis of the code	PASS
L2	Instruction surface (what it tells the agent)	PASS
L3	Class-specific surface	WARN
L4	Behavioural (sandbox)	SKIPPED

What the source does

Filesystem: declared (2 observation(s))
Network: declared (1 observation(s))
Shell: none-observed
Dependencies: not all pinned
Secrets in source: none-found

Findings (12)

MEDIUMFilesystem / path · mcp.destructive_tools · CWE-22, CWE-59

delete_correspondent, delete_custom_field, delete_document_note, delete_document_type, delete_mail_rule, delete_tag

Why it matters. 6 tool(s) can delete or overwrite

Fix. prefer a read-only mode or scoped tokens; the page states the blast radius

LOWInventory / provenance · inv.hidden_file · CWE-1104

.node-version

.node-version

Why it matters. hidden member outside the usual dotfiles

Fix. review its purpose