playbooks

home / mcp / paperless mcp server

Paperless MCP Server

Provides an MCP server to manage Paperless-NGX documents, tags, correspondents, and document types through a unified API.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "baruchiro-paperless-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@baruchiro/paperless-mcp@latest"
      ],
      "env": {
        "PAPERLESS_URL": "http://your-paperless-instance:8000",
        "PAPERLESS_API_KEY": "your-api-token",
        "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
      }
    }
  }
}

You can run a Paperless-NGX MCP server that exposes a curated set of Document, Tag, Correspondent, and Custom Field operations to manage your Paperless-NGX instance. This MCP server enables you to perform common tasks from a single, consistent API surface, empowering you to automate workflows and integrate Paperless-NGX with your tools and clients.

How to use

To use this MCP server, you connect an MCP client to the server endpoint and invoke the available tools to manage documents, tags, correspondents, and document types in Paperless-NGX. Typical tasks include listing documents, searching content, downloading files, creating and updating tags, and bulk editing documents. Each operation is designed to be simple to call from your automation scripts or editor extensions, and the server validates input and returns structured results.

How to install

Prerequisites: you need Node.js and npm installed on your machine if you plan to run the MCP server in stdio mode. Docker is optional if you prefer the HTTP/Docker route.

1) Install dependencies and run in stdio mode using the provided configuration snippet.

"paperless": {
  "command": "npx",
  "args": [
    "-y",
    "@baruchiro/paperless-mcp@latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

Additional sections

Configuration notes and usage details are provided to help you run and manage the MCP server smoothly. The server runs in stdio mode by default, suitable for local use and direct integrations. If you prefer remote access, you can run it in HTTP mode with a container and environment-based configuration.

Available tools

list_documents

Get a paginated list of all documents with optional filtering by page and page_size.

get_document

Retrieve a specific 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.

get_document_thumbnail

Fetch a thumbnail (image preview) for a document by its ID.

bulk_edit_documents

Perform bulk operations on multiple documents, such as adding tags, changing correspondents, merging, splitting, and more.

post_document

Upload a new document to Paperless-NGX with optional metadata like title, correspondent, document type, and tags.

list_tags

Retrieve all tags defined in Paperless-NGX.

create_tag

Create a new tag with optional color, match pattern, and matching algorithm.

list_correspondents

Retrieve all correspondents.

create_correspondent

Create a new correspondent with an optional match pattern.

list_document_types

Retrieve all document types.

create_document_type

Create a new document type with optional matching configuration.

list_custom_fields

Retrieve all custom fields.

get_custom_field

Get a specific custom field by ID.

create_custom_field

Create a new custom field with a defined data type.

update_custom_field

Update an existing custom field.

delete_custom_field

Delete a custom field by ID.

bulk_edit_custom_fields

Perform bulk operations on multiple custom fields, such as deletion.