Log inSubmit server
Paperless Ngx logo

Paperless Ngx

Exposes Paperless-NGX’s REST API to MCP clients for document management, search, metadata, workflows, mail, and more.

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-2": {
      "command": "npx",
      "args": [
        "-y",
        "paperless-ngx-mcp"
      ],
      "env": {
        "PAPERLESS_URL": "YOUR_VALUE_HERE",
        "PAPERLESS_API_KEY": "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.

Automated check passed— started and listed 109 tools correctly (18d ago).

Overview

Paperless-ngx MCP server exposes the Paperless-NGX REST API to AI assistants through MCP tools. It supports document search, uploads, downloads, metadata changes, tagging, workflows, mail configuration, sharing, versions, notes, trash, and task inspection. Run it with npx, Docker, a Claude Desktop extension, or another MCP client using a Paperless URL and API token. Choose it when an assistant needs to manage a Paperless-NGX instance rather than only retrieve document content.

Use cases

  • Search documents by text, tag, or metadata
  • Update document tags, correspondents, and types
  • Upload documents and manage document versions
  • Create Paperless-NGX workflows and mail rules
  • Inspect tasks, trash, notes, and share links

Key features

  • Paperless-NGX REST API exposed through MCP tools
  • Document search, editing, upload, download, and version management
  • CRUD operations for tags, correspondents, types, fields, and storage paths
  • Workflow, mail, sharing, saved-view, task, and trash support
  • Confirmation requirements for destructive operations
  • stdio and Streamable HTTP transports

Tools109

What Paperless Ngx lets your agent do. Expand a tool for its parameters.

Verified live~29.0k tokens of context

Security & health

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

ActiveLast checked 1d ago

Recent health check succeeded.

8/8 checks healthy over the last 30d

What it can do

From the 109 tools this server returned when we ran it; 109 declare their own safety hints.

Can delete or modify data · 25Handles credentials · 8Makes network requests · 10Read-only tools · 84
Network at startup3 connections
Files written at startupNone
Install scriptsNone
npm provenanceSigned build
Package age172 days
Maintainers1

Observed 2026-10-25 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 14d ago via OSV.dev · paperless-ngx-mcp (npm)

Adoption & maintenance

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

GitHub stars13Stargazers on the source repository.
npm downloads1.2kPackage downloads in the last 30 days.
Last commit1mo agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed109Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Paperless Ngx works

What Paperless-ngx MCP server does

Paperless-ngx MCP server connects an MCP-compatible assistant to a Paperless-NGX instance and exposes the service’s REST API as callable tools. The supported API areas include 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.

Document operations cover listing, searching, retrieving content and metadata, downloading files, viewing previews and thumbnails, uploading documents and versions, sending documents by email, updating records, and inspecting history. The server also supports bulk edits and document merging. Related resource types can be listed, created, updated, or deleted where the Paperless-NGX API provides those operations.

How it works

The server communicates with Paperless-NGX using its base URL and API token, then presents the API operations as MCP tools for the connected assistant. It can run as a standard stdio process, including through npx or Docker, or as a Streamable HTTP process using the --http option.

Tool names use action-oriented prefixes such as list_, get_, create_, update_, and delete_, which can help organize client permission allowlists. Destructive operations require explicit confirmation in the tool input. This applies to deletion tools, emptying the trash, merging documents as versions, and bulk deletion. Bulk edits also reject filters that Paperless-NGX would silently ignore. The triage_inbox prompt proposes changes and waits for approval before writing them.

Setup and configuration

Install the Paperless-ngx MCP server with npx -y paperless-ngx-mcp, or use the published multi-architecture image ghcr.io/cubinet-code/paperless-ngx-mcp. Configure these required environment variables:

  • PAPERLESS_URL: the base URL of the Paperless-NGX instance.
  • PAPERLESS_API_KEY: an API token generated from the Paperless-NGX user profile.

PAPERLESS_PUBLIC_URL is optional. When set, it supplies the public address used in browser links to documents; without it, the server falls back to PAPERLESS_URL. Equivalent command-line options can override environment values. The available options include --baseUrl, --token, --publicUrl, --http, and --port.

The Claude Desktop extension requests the Paperless URL and token during installation. For other clients, add the server command and environment values to the client’s MCP configuration. Docker can run the server over stdio or expose Streamable HTTP on a local port. The HTTP mode has no authentication, so it should not be placed on an untrusted network.

Tools and capabilities

The Paperless-ngx MCP server groups tools across twelve documented domains. Capabilities include:

  • Searching documents, including autocomplete and suggestion queries.
  • Reading, editing, downloading, uploading, emailing, versioning, and deleting documents.
  • Managing tags, correspondents, document types, custom fields, and storage paths.
  • Creating and maintaining saved views, share links, and share-link bundles.
  • Defining workflow triggers and actions.
  • Inspecting mail accounts, rules, tasks, notes, and trash-related resources where exposed by the API.

The project targets Paperless-NGX 3.2 and is tested against version 3.2.1. Paperless-NGX 2.x requires the paperless-ngx-mcp@3.1.1 package instead.

Limitations and notes

The Streamable HTTP transport does not provide authentication. Keep deployments limited to trusted networks or place suitable access controls in front of them. The server’s compatibility target is Paperless-NGX 3.2; older versions are not supported by the current release. API coverage is checked against Paperless-NGX’s schema, but support still follows the target version’s available endpoints. The package is distributed under the ISC license.

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 assistants to a Paperless-NGX instance through its REST API. Its main tools search, read, edit, upload, download, tag, version, and delete documents, while also managing workflows, mail, sharing, metadata resources, tasks, notes, and trash.

Install it with `npx -y paperless-ngx-mcp`, use the published Docker image, or install the Claude Desktop extension. Configure `PAPERLESS_URL` and `PAPERLESS_API_KEY` in the MCP client. The project also provides client setup examples for Claude Code, Codex CLI, Cursor, Cline, and VS Code.

The current release targets Paperless-NGX 3.2 and is tested against 3.2.1. Older Paperless-NGX versions are not supported by the current release. For Paperless-NGX 2.x, use `paperless-ngx-mcp@3.1.1`.

Yes, Paperless-ngx works with Cursor as an MCP server. Add the npx command and configure `PAPERLESS_URL` plus `PAPERLESS_API_KEY` in Cursor’s MCP configuration. The repository also provides a Cursor installation link with placeholder values that must be replaced.

Run the `ghcr.io/cubinet-code/paperless-ngx-mcp` image and pass `PAPERLESS_URL` and `PAPERLESS_API_KEY`. Docker supports stdio inside an MCP client and Streamable HTTP with `--http` and `--port`. HTTP mode has no authentication and should remain off untrusted networks.

Related MCP servers

All in Developer Tools 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-2?style=directory)](https://allmcps.com/mcp/paperless-ngx-2)
HTML Embed
<a href="https://allmcps.com/mcp/paperless-ngx-2"><img src="https://allmcps.com/api/badge/paperless-ngx-2?style=directory" alt="Paperless Ngx on AllMCPs" /></a>