# Paperless-ngx [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/tobee89/mcp-paperless-ngx  
**GitHub Stars:** 2  
**npm Downloads (last month):** 2576  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/paperless-ngx

## Description
MCP server for Paperless-ngx 3.x — full REST API coverage, schema-aware, token-frugal.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "paperless-ngx": {
    "command": "npx",
    "args": ["-y","mcp-paperless-ngx"],
    "env": {
      "PAPERLESS_URL": "",
      "PAPERLESS_TOKEN": "",
      "PAPERLESS_API_KEY": "",
      "PAPERLESS_PUBLIC_URL": "",
      "PAPERLESS_TOOLSETS": "",
      "PAPERLESS_READ_ONLY": "",
      "PAPERLESS_HEADERS": "",
      "PAPERLESS_DOWNLOAD_DIR": ""
    }
  }
}
```

**Requires environment variables:** `PAPERLESS_URL`, `PAPERLESS_TOKEN`, `PAPERLESS_API_KEY`, `PAPERLESS_PUBLIC_URL`, `PAPERLESS_TOOLSETS`, `PAPERLESS_READ_ONLY`, `PAPERLESS_HEADERS`, `PAPERLESS_DOWNLOAD_DIR` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/paperless-ngx/readme_