Paperless-NGX MCP Server

@baruchiro

About Paperless-NGX MCP Server

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.

#ai #mcp #document-management #paperless-ngx #mcp-server

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "paperless-mcp": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "docker-compose.e2e.yml",
        "up",
        "-d"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Paperless-NGX MCP Server?

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

How to use Paperless-NGX MCP Server?

Install via npx -y @baruchiro/paperless-mcp@latest or run the Docker image ghcr.io/baruchiro/paperless-mcp:latest. Configure your MCP client with the required environment variables PAPERLESS_URL and PAPERLESS_API_KEY. Then ask Claude to manage your documents, tags, correspondents, etc.

Key features of Paperless-NGX MCP Server?

List, search, get, download, and upload documents
Bulk edit documents (tags, correspondents, merge, split, delete)
Create and list tags, correspondents, document types
Full CRUD for custom fields
List mail accounts for automatic email ingestion
File upload via base64 or local filesystem path

Use cases of Paperless-NGX MCP Server?

"Show me all documents tagged as 'Invoice'"
"Create a new tag called 'Receipts' with color #FF0000"
"Download document #123"
"Upload a new document with title, correspondent, and tags"
"Merge documents 6, 7, 8 and keep metadata from document 6"

FAQ from Paperless-NGX MCP Server

What environment variables are required?

PAPERLESS_URL (your Paperless-NGX base URL) and PAPERLESS_API_KEY (your API token) are required. Optional variables include PAPERLESS_PUBLIC_URL, PAPERLESS_API_VERSION, and PAPERLESS_MCP_UPLOAD_PATHS.

How do I get my Paperless-NGX API token?

Log into your Paperless-NGX instance, click your username in the top right, select "My Profile", then click the circular arrow button to generate a new token.

Is there a file size limit for uploads?

Yes, the file size limit is 100MB for both base64 and filesystem upload modes.

What API version should I use for Paperless-ngx v3+?

The default PAPERLESS_API_VERSION is 5. If you see HTTP 406 errors, set it to 10 for Paperless-ngx v3+.

Can I restrict which directories are allowed for filesystem uploads?

Yes, set the PAPERLESS_MCP_UPLOAD_PATHS environment variable to a colon-separated list of allowed directories. Without this, any file on the server's filesystem could be uploaded.

Frequently asked questions