Log inSubmit server
Paperless Ngx logo

Paperless Ngx

Connects AI clients to Paperless-ngx 3.x through schema-aware REST API tools, with read-only and token-conscious modes.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Paperless Ngx

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "paperless-ngx": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-paperless-ngx"
      ],
      "env": {
        "PAPERLESS_URL": "YOUR_VALUE_HERE",
        "PAPERLESS_TOKEN": "YOUR_VALUE_HERE",
        "PAPERLESS_API_KEY": "YOUR_VALUE_HERE",
        "PAPERLESS_PUBLIC_URL": "YOUR_VALUE_HERE",
        "PAPERLESS_TOOLSETS": "YOUR_VALUE_HERE",
        "PAPERLESS_READ_ONLY": "YOUR_VALUE_HERE",
        "PAPERLESS_HEADERS": "YOUR_VALUE_HERE",
        "PAPERLESS_DOWNLOAD_DIR": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

We couldn’t confirm it starts correctly

The install command installed and started the server, which then stopped for configuration (such as an API key) that our sandbox does not have — expected for servers that connect to your account.

npx -y mcp-paperless-ngx

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 3d ago.

Overview

Paperless-ngx MCP server exposes the Paperless-ngx 3.x REST API v10 to MCP clients through a Node.js stdio process. It provides tools for documents, metadata, saved views, sharing, workflows, system operations, and optionally mail and administration. Responses are trimmed to reduce OCR and nested-object context costs, while document content is available through a separate paginated tool. Use it when an agent needs to search, organize, inspect, or manage a Paperless-ngx archive.

Use cases

  • Search an archive for documents matching a description
  • Review and update document metadata
  • Triage unprocessed documents with user approval
  • Audit public share links for missing expiration
  • Download or inspect document content

Key features

  • Paperless-ngx 3.x REST API v10 coverage
  • Document and metadata management tools
  • Server-side response trimming and paginated OCR access
  • Configurable toolsets and read-only mode
  • Share-link auditing and inbox-triage prompts

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

10/10 checks healthy over the last 55d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 20h ago via OSV.dev · mcp-paperless-ngx (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars2Stargazers on the source repository.
npm downloads2.6kPackage downloads in the last 30 days.
Last commit2mo agoMost recent push to the default branch.
Install checkRunsOur sandbox started it; it then asked for an API key or config.

How Paperless Ngx works

What Paperless-ngx MCP server does

The Paperless-ngx MCP server connects an MCP-compatible client to a Paperless-ngx 3.x instance through its REST API. It accounts for the documented API v10 endpoints, exposing supported operations as tools and recording exclusions rather than silently ignoring endpoints. Paperless-ngx 2.x is not supported because the implementation depends on API v10 behavior and resources.

The default tool surface covers document search and management, metadata such as tags and correspondents, custom fields, saved views, sharing, workflows, system information, statistics, tasks, and trash. Mail-related tools and administrative tools are disabled by default. Prompts are also provided for inbox triage, vague document searches, and reviewing public share links.

How it works

The Paperless-ngx MCP server runs with Node.js 20 or newer and communicates with the configured Paperless-ngx base URL using an API token. It is intended to be launched by an MCP client, commonly with npx -y mcp-paperless-ngx.

The implementation limits response size before results reach the model. Document lists use selected fields instead of returning full OCR text, and document content is retrieved separately with pagination. Global search results summarize documents and reduce other object types to identifying fields. Workflows, mail rules, groups, and tasks are also summarized unless a full response is explicitly requested.

Toolsets let an operator choose which groups of tools are visible. Read-only mode removes write tools entirely. Destructive operations are marked for client confirmation, and bulk operations require explicit ID lists rather than applying changes to every item matching a filter.

Setup and configuration

Set PAPERLESS_URL to the Paperless-ngx base URL and PAPERLESS_TOKEN to an API token from the Paperless-ngx user profile. PAPERLESS_API_KEY can be used as an alternative token variable. The --check option verifies connectivity and exits; --list-tools displays the enabled tools.

PAPERLESS_PUBLIC_URL changes the URL used in links when the externally reachable address differs from the configured service URL. PAPERLESS_TOOLSETS accepts a comma-separated selection or all, while PAPERLESS_READ_ONLY=true enables read-only exposure. Additional request headers can be supplied through PAPERLESS_HEADERS, including headers required by forward-auth proxies. Downloaded files use PAPERLESS_DOWNLOAD_DIR, or the system temporary directory when unset.

Command-line options for the URL, token, public URL, toolsets, and read-only mode override their environment-variable counterparts. The server expects Paperless-ngx API version 10 by default.

Tools and capabilities

The Paperless-ngx MCP server groups capabilities into these toolsets:

  • documents: search, read, update, delete, upload, download, notes, bulk operations, and PDF operations
  • metadata: tags, correspondents, document types, and storage paths
  • customfields: custom field definitions
  • views: saved views
  • sharing: share links and share link bundles
  • workflows: automation rules, triggers, and actions
  • system: global search, statistics, status, tasks, and trash
  • mail: IMAP accounts, mail rules, and processed mail
  • admin: users, groups, profile, configuration, and logs, read-only

The mail and admin groups are off by default. The server also registers prompts for proposing inbox metadata changes, finding documents from vague descriptions, and auditing public links that do not expire.

Limitations and notes

Only Paperless-ngx 3.x is supported. Creating a share link produces a publicly reachable URL. Credential-adjacent operations such as token generation and TOTP enrollment are intentionally excluded.

Reducing toolsets lowers the context used by tool definitions. The default configuration exposes more tools than a narrowly scoped documents,metadata configuration, while all enables the optional groups as well.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Paperless Ngx

Paperless-ngx is an MCP server that connects AI clients to Paperless-ngx 3.x through its REST API v10. Its main tools search, read, update, upload, download, and organize documents, metadata, workflows, sharing, and system resources while limiting large OCR responses.

Run it through `npx -y mcp-paperless-ngx` from your MCP client configuration. Set `PAPERLESS_URL` and `PAPERLESS_TOKEN` in the client environment, then use `--check` to verify connectivity.

Yes, Paperless-ngx works with Cursor through a standard MCP server configuration. Add a server entry that runs `npx` with `-y mcp-paperless-ngx`, and provide `PAPERLESS_URL` and `PAPERLESS_TOKEN` in its environment.

Set `PAPERLESS_READ_ONLY=true` or start the server with `--read-only`. This removes write tools from the exposed tool list instead of waiting until a write call is attempted.

Set `PAPERLESS_TOOLSETS` to only the groups the client needs, such as `documents,metadata`. Mail and admin tools are already disabled by default, and narrower toolsets reduce the tool definitions sent to the model.

Related MCP servers

All in Finance & Fintech All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewPaperless Ngx AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/paperless-ngx?style=directory)](https://allmcps.com/mcp/paperless-ngx)
HTML Embed
<a href="https://allmcps.com/mcp/paperless-ngx"><img src="https://allmcps.com/api/badge/paperless-ngx?style=directory" alt="Paperless Ngx on AllMCPs" /></a>