Paperless-NGX
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.
What is Paperless-NGX?
Paperless-NGX is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to 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 i...
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.
This server falls under the File Systems category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- An MCP (Model Context Protocol) server for interacting with
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx paperless-ngx-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Paperless-NGX
Paperless-NGX MCP Server is a TypeScript MCP server that connects Claude and other AI clients to a self-hosted Paperless-NGX document management instance, exposing tools for searching, listing, downloading, uploading, bulk-editing, and managing documents, tags, correspondents, document types, and storage paths. It enables natural-language document management workflows — finding invoices, tagging receipts, merging scanned PDFs, or rotating pages — without needing to open the Paperless-NGX web UI. Home-office users and small businesses running self-hosted document archives use it to automate document organisation through conversational AI.
Prerequisites
- A running Paperless-NGX instance accessible over HTTP or HTTPS
- A Paperless-NGX API token (generated from your user profile in the Paperless-NGX web UI)
- Node.js 18 or higher and npx available on your PATH
- An MCP-compatible client such as Claude Desktop or Cursor
Generate a Paperless-NGX API token
Log into your Paperless-NGX web interface, click your username in the top right, select My Profile, and click the circular arrow button to generate a new API token. Copy the token.
Install the MCP server globally
Install the paperless-mcp package globally from npm to make it available as a command.
npm install -g paperless-mcpTest the connection
Verify the server can reach your Paperless-NGX instance by running it directly with your URL and token as arguments.
npx paperless-mcp http://your-paperless-instance:8000 your-api-tokenAdd the server to your MCP client configuration
Edit your claude_desktop_config.json to register the server, passing the Paperless-NGX URL and API token as command-line arguments.
Restart your MCP client and verify
Restart Claude Desktop (or your client of choice). The paperless server's tools should now be available — ask Claude to list your documents to confirm.
Paperless-NGX Examples
Client configuration
Register the Paperless-NGX MCP server in Claude Desktop. The Paperless-NGX URL and API token are passed as positional arguments to the npx command.
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": [
"paperless-mcp",
"http://your-paperless-instance:8000",
"your-api-token"
]
}
}
}Prompts to try
Example natural-language prompts for managing documents in Paperless-NGX through Claude.
- "Show me all documents tagged as Invoice from the last 3 months"
- "Search for documents containing 'tax return 2024'"
- "Create a new tag called Receipts"
- "Download document number 123"
- "Add the tag 'Receipts' to documents 45, 46, and 47 at once"
- "List all correspondents in my Paperless-NGX instance"
- "Upload the file at /tmp/bank_statement.pdf and set its document type to Bank Statement"Troubleshooting Paperless-NGX
Connection refused or timeout when the MCP server tries to reach Paperless-NGX
Confirm your Paperless-NGX instance is running and reachable at the URL you configured. From the machine running the MCP server, run `curl http://your-paperless-instance:8000/api/` to test connectivity. If Paperless-NGX is on a different machine, ensure firewall rules allow the connection.
Authentication error — 401 Unauthorized
Regenerate your API token in the Paperless-NGX web UI (My Profile → circular arrow button) and update the token in your MCP client config. Tokens are user-scoped; ensure the token belongs to a user with sufficient permissions.
bulk_edit_documents returns an error for merge or split operations
Merge and split operations require Paperless-NGX 2.x or later. Verify your instance version at /api/ and upgrade if necessary. For split, ensure the pages string uses the correct format, e.g., "[1-2,3-4,5]" with square brackets.
Frequently Asked Questions about Paperless-NGX
What is Paperless-NGX?
Paperless-NGX is a Model Context Protocol (MCP) server that 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. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Paperless-NGX?
Follow the installation instructions on the Paperless-NGX GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Paperless-NGX?
Paperless-NGX works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Paperless-NGX free to use?
Yes, Paperless-NGX is open source and available under the ISC License license. You can use it freely in both personal and commercial projects.
Paperless-NGX Alternatives — Similar File Systems Servers
Looking for alternatives to Paperless-NGX? Here are other popular file systems servers you can use with Claude, Cursor, and VS Code.
Electerm
★ 14.1k📻Terminal/ssh/sftp/ftp/telnet/serialport/RDP/VNC/Spice client(linux, mac, win)
Plik
★ 1.8kPlik is a temporary file upload system (Wetransfer like) in Go.
Kordoc
★ 957An MCP server that parses South Korean document formats like HWP, HWPX, and PDF into Markdown. It features specialized table reconstruction and security-hardened extraction optimized for administrative and public institution files.
macOS Automator
★ 801A Model Context Protocol server that enables execution of AppleScript and JavaScript for Automation scripts on macOS, allowing programmatic control of applications and system functions through a rich knowledge base of pre-defined scripts.
PDF Reader
★ 723Enables reading, searching, and metadata extraction from PDF files without loading the entire content into the context window. It provides efficient tools for text cleaning, page-specific extraction, and context-aware search results.
Filesystem MCP Server
★ 643Provides comprehensive filesystem operations (read, write, list, create, delete, move files and directories) through the Model Context Protocol with Streamable HTTP transport and built-in security through configurable root directory restrictions.
Browse More File Systems MCP Servers
Explore all file systems servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Paperless-NGX in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Paperless-NGX?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.