Paperless

You run a Paperless-ngx MCP Server to let AI assistants and other MCP clients interact with your Paperless document management system. It supports both local stdio transports and HTTP-based transports, making it easy to connect from various environments while keeping your Paperless data secure and searchable through familiar MCP tools.

How to use

Connect your MCP client to your Paperless MCP Server using either the HTTP transport or the stdio transport. With HTTP, your server acts as a standalone service that the client can reach over the network. With stdio, the MCP server runs locally alongside the client process, communicating through standard input and output. You can perform common document operations such as searching, retrieving content, creating or updating documents, and managing related metadata like correspondents, document types, tags, and custom fields. Security can be enhanced by enabling an MCP authentication token when exposing HTTP.

How to install

Prerequisites you need before installing the MCP server:

• A running Paperless-ngx instance
• Paperless-ngx API token
• Docker and Docker Compose (optional for containerized deployment)

Choose your preferred deployment method. The MCP server provides both HTTP transport and stdio transport options. Follow the steps below for each method.

PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TOKEN=your_paperless_api_token_here
MCP_TRANSPORT=http
MCP_HTTP_PORT=8080

# Run via Docker for HTTP transport
docker run --rm --env-file .env -p 8080:8080  cbinckly/paperless-mcp-go:latest

HTTP transport setup

To run the MCP server as a standalone HTTP service, configure the environment and start the server. You will access the MCP endpoint at the provided port.

Example start command and URL:

export PAPERLESS_URL=https://paperless.example.com
export PAPERLESS_TOKEN=your_token_here
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=8080

./paperless-mcp
# Then open http://localhost:8080/mcp

Stdio transport setup

To run the MCP server locally with stdio transport, use a local process that launches the MCP server and communicates via standard IO streams.

Example container-based stdio setup using Docker (as shown in the configuration example):

{
  "mcpServers": {
    "paperless_mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull=always",
        "cbinckly/paperless-mcp-go:latest"
      ],
      "env": {
        "PAPERLESS_URL": "https://paperless.example.com",
        "PAPERLESS_TOKEN": "your_paperless_api_token_here",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Security and access control

You can enable an optional authentication token for MCP clients when using HTTP transport. Set MCP_AUTH_TOKEN in the environment; clients must present it as a Bearer token in the Authorization header to access MCP endpoints. This helps protect your Paperless data from unauthorized access.

Notes

The server supports a complete set of document and metadata tools, including searching, retrieving, creating, updating, and deleting documents, as well as managing correspondents, document types, tags, storage paths, and custom fields. It also includes utility tools like ping and server_info for quick health checks and status reporting.

Available tools

search_documents

Search documents by text query with pagination, returning metadata and previews as available.

find_similar_documents

Find documents similar to a given document based on content or metadata.

get_document

Retrieve a document by ID along with all its metadata.

get_document_content

Get the textual content of a document.

create_document

Create a new document with associated metadata.

update_document

Update metadata for an existing document.

delete_document

Delete a document from the system.

bulk_edit_documents

Apply bulk operations to multiple documents, such as tagging or updating fields.

list_correspondents

List all correspondents with pagination.

get_correspondent

Get details for a specific correspondent by ID.

create_correspondent

Create a new correspondent entry.

update_correspondent

Update an existing correspondent's information.

delete_correspondent

Delete a correspondent.

list_document_types

List all document types with pagination.

get_document_type

Get details for a document type by ID.

create_document_type

Create a new document type.

update_document_type

Update document type information.

delete_document_type

Delete a document type.

list_tags

List all tags with pagination.

get_tag

Get tag details by ID.

create_tag

Create a new tag.

update_tag

Update tag information.

delete_tag

Delete a tag.

list_storage_paths

List all storage paths with pagination.

get_storage_path

Get storage path details by ID.

create_storage_path

Create a new storage path.

update_storage_path

Update storage path information.

delete_storage_path

Delete a storage path.

list_custom_fields

List all custom fields with pagination.

get_custom_field

Get custom field details by ID.

create_custom_field

Create a new custom field.

update_custom_field

Update custom field information.

delete_custom_field

Delete a custom field.

ping

Test tool that returns pong.

server_info

Get MCP server and Paperless connection information.