home / mcp / paperless-ngx mcp server

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.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "nloui-paperless-mcp": {
      "url": "http://your-paperless-instance:8000"
    }
  }
}

You can connect Claude or another MCP client to a Paperless-NGX API server through an MCP server. This setup lets you manage documents, tags, correspondents, and document types using simple, chat-based commands while Paperless-NGX handles the heavy lifting on your side.

How to use

To use this MCP server, configure a client to connect to either the remote Paperless-NGX MCP endpoint or run the local MCP server in stdio mode. You can perform common actions like listing documents, searching, tagging, uploading new documents, and managing correspondents and document types. Use natural language prompts to perform these operations, and the MCP server translates your requests into Paperless-NGX API calls.

How to install

Prerequisites you need before installing: Node.js and npm installed on your machine.

Step 1: Install the MCP server globally.

npm install -g paperless-mcp

Configuration and running modes

You can connect to Paperless-NGX via a remote MCP endpoint or run the MCP server locally in stdio mode.

Remote MCP endpoint (http) usage example shows how to point your MCP client at Paperless-NGX. The following configuration uses the HTTP transport and passes the API token in the arguments.

{
  "mcpServers": [
    {
      "type": "http",
      "name": "paperless",
      "url": "http://your-paperless-instance:8000",
      "args": []
    }
  ]
}

Starting the MCP server in stdio mode

If you prefer running the MCP server locally in stdio mode, use the standard npm start flow shown here.

npm run start -- <baseUrl> <token>

Running the MCP server over HTTP

To expose the MCP API over HTTP, run the server with the http transport and an optional port. This mode uses Express and is stateless for each request.

npm run start -- <baseUrl> <token> --http --port 3000

Additional configuration options

- The http-based endpoint is suitable for remote clients and other automation that can reach your Paperless-NGX instance. - The stdio-based endpoint is convenient for CLI usage and direct integrations where you want the MCP server to communicate via standard input/output streams.

Examples of common tasks you can perform

- Show all documents tagged as a specific tag - Search for documents containing particular text - Create new tags or document types - Upload new documents from base64 content - Download documents by ID - Manage correspondents and document types

Security considerations

Protect your API tokens and limit access to the MCP endpoints. Use HTTPS in production and rotate tokens periodically.

Troubleshooting tips

If you encounter connection errors, verify the Paperless-NGX URL and API token, ensure the MCP server is reachable from your client, and check that the correct transport (http or stdio) is configured.

Notes

This MCP server implements the Paperless-NGX REST API surface for document, tag, correspondent, and document type operations, enabling you to script and automate common workflows.

Available tools

list_documents

Get a paginated list of all documents. You can specify page and page_size to control the results.

get_document

Retrieve a single document by its ID.

search_documents

Perform a full-text search across documents using a query string.

download_document

Download a document file by its ID, with an option to fetch the original file.

bulk_edit_documents

Apply bulk operations to multiple documents, such as adding tags, changing correspondents, splitting or merging, and other batch actions.

post_document

Upload a new document to Paperless-NGX, including file data, metadata, and relationships.

list_tags

Retrieve all tags defined in Paperless-NGX.

create_tag

Create a new tag with optional color and matching rules.

list_correspondents

Retrieve all correspondents.

create_correspondent

Create a new correspondent with optional matching rules.

list_document_types

Retrieve all document types.

create_document_type

Create a new document type with optional matching rules.