paperless

The Paperless-NGX MCP Server exposes a set of tools that let Claude interact with a Paperless-NGX instance. You can list, search, and retrieve documents; manage tags, correspondents, and document types; and perform bulk operations on documents. Typical interactions include listing documents, searching by text, downloading a document, and uploading new documents with metadata. The server also provides endpoints to create and manage tags, correspondents, and document types, enabling you to organize and classify your Paperless-NGX data from your chat workflows. To use the server, ensure you have configured it with your Paperless-NGX URL and an API token as shown in the Quick Start, then invoke the available tools through Claude prompts.

Available core tools include: list_documents, get_document, search_documents, download_document, bulk_edit_documents, post_document, list_tags, create_tag, list_correspondents, create_correspondent, list_document_types, and create_document_type. Each tool accepts parameters as described in the README, for example list_documents accepts page and page_size, while bulk_edit_documents supports multiple methods like add_tag, set_correspondent, merge, split, rotate, and more with method-specific fields. Use these tools to craft precise requests such as filtering documents by a keyword, tagging multiple documents, or uploading a new document with its metadata. You can combine these operations to automate common Paperless-NGX workflows directly from Claude.

Prerequisites:

• Node.js and npm installed on your system
• Access to a shell or terminal where you run npm commands

Step-by-step installation:

1. Install the MCP server globally via npm:

npm install -g paperless-mcp

2. Ensure you have a Paperless-NGX instance reachable at a URL like http://your-paperless-instance:8000 and generate an API token from Paperless-NGX as described in the README.

3. Run or configure the MCP server in your Claude setup. An example configuration snippet is provided in the Quick Start section of the README:

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
    }
  }
}

4. Start using the server by invoking Claude with the configured MCP server name (paperless in this example). For local testing, you can verify the server start by running the same command the config uses:

npm run start -- <baseUrl> <token>

5. If you need to run the server directly without Claude, start it with the provided args:

npx paperless-mcp http://your-paperless-instance:8000 your-api-token

Tips and common issues:

• Ensure the Paperless-NGX URL is reachable from the environment where the MCP runs; network access and CORS are not typically an issue for backend MCP usage but can affect connectivity.
• Keep your API token secure; rotate tokens periodically and update the MCP configuration accordingly.
• When using bulk edits, double-check IDs (documents, tags, correspondents, etc.) to avoid unintended data changes.
• If you encounter validation errors, verify parameter names and types against the API expectations in the README's endpoint examples.
• The MCP server uses a TypeScript-based framework (litemcp) with Zod for schema validation, so you can rely on strong input validation and error messages for invalid requests.