Paperless-NGX MCP Server

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, and document types in your Paperless-NGX instance.

How to use Paperless-NGX MCP Server?

Install globally via npm install -g paperless-mcp, then add it to your Claude MCP configuration (VSCode extension or desktop app) with the command npx paperless-mcp <baseUrl> <token>. Obtain an API token from your Paperless-NGX profile page.

Key features of Paperless-NGX MCP Server

• List, get, search, download, and upload documents
• Bulk edit documents (set correspondent, type, tags, merge, split, etc.)
• Create and list tags with color and matching rules
• Create and list correspondents and document types
• Supports both stdio and HTTP (Streamable HTTP Transport) modes

Use cases of Paperless-NGX MCP Server

• Search for documents by full-text query or tag
• Automate document tagging and correspondent assignment
• Upload new documents with metadata (title, date, tags)
• Perform bulk operations like merging or splitting documents
• Integrate Paperless-NGX document management into AI workflows

FAQ from Paperless-NGX MCP Server

What are the prerequisites?

A running Paperless-NGX instance and a valid API token from that instance.

How do I get an API token?

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

What transport modes are supported?

Two modes: stdio (default) and HTTP (Streamable HTTP Transport) using the --http flag, optionally with --port (default 3000).

What happens if the Paperless-NGX server is unreachable?

The server will show clear error messages indicating the URL or token is incorrect, the server is unreachable, or the operation failed.

Can I run it as an HTTP service?

Yes, run with npm run start -- <baseUrl> <token> --http --port 3000. The MCP API is available at POST /mcp.