mcp-paperless-ngx

MCP server for Paperless-ngx using the streamable HTTP transport protocol.

Features

Resources

URI	Description
paperless://openapi	Full OpenAPI spec for the Paperless-ngx REST API
paperless://server	Configured server base URL
paperless://token	API auth token

Tools (read-only)

• list_documents — list documents with filters (tag, correspondent, document type, full-text query)
• get_document — retrieve a single document with all metadata
• get_document_content — retrieve extracted text content of a document
• get_document_suggestions — AI-generated metadata suggestions for a document
• list_tags — list all tags
• list_correspondents — list all correspondents
• list_document_types — list all document types
• list_workflows — list all sorting workflows
• list_workflow_triggers — list all workflow triggers
• list_workflow_actions — list all workflow actions

Tools (write — metadata and workflow creation)

• create_tag — create a new tag
• create_correspondent — create a new correspondent
• create_document_type — create a new document type
• create_workflow_trigger — create a workflow trigger (conditions)
• create_workflow_action — create a workflow action (assignments)
• create_workflow — create a complete workflow linking triggers and actions

Prompts

• get_inbox_documents — formatted overview of all inbox documents
• get_document_data_for_rule_creation(document_id) — detailed document data to help design a sorting rule
• create_sorting_rule(document_id?) — guided walkthrough for creating a sorting workflow

Configuration

Create ~/.config/mcp-paperless-ngx/config.toml:

[paperless]
server_url = "http://your-paperless-server:8000"
token = "your-api-token"
inbox_tag_id = 1  # ID of the tag used for the inbox view

Override the config path with the PAPERLESS_MCP_CONFIG environment variable.

Running

# Install dependencies
uv sync

# Start the server (listens on 0.0.0.0:8000/mcp)
uv run mcp-paperless-ngx

The MCP endpoint is available at http://localhost:8000/mcp (streamable HTTP).

Docker

Quick start

# Pull and run (replace values in the environment or mount a config file)
docker run -d \
  --name mcp-paperless-ngx \
  -p 8000:8000 \
  -v ./config:/config:ro \
  ghcr.io/Code-Omega-Solutions/mcp-paperless-ngx:latest

Create ./config/config.toml before starting (see Configuration above).

docker-compose

# 1. Create the config directory and file
mkdir config
cat > config/config.toml <<'EOF'
[paperless]
server_url = "http://your-paperless-server:8000"
token = "your-api-token"
inbox_tag_id = 1
EOF

# 2. Start the service
docker compose up -d

# 3. Check it is healthy
docker compose ps

The docker-compose.yml in this repository mounts ./config as read-only and includes a health check that verifies the server is accepting TCP connections on port 8000.

Building locally

docker build -t mcp-paperless-ngx .
docker run -d -p 8000:8000 -v ./config:/config:ro mcp-paperless-ngx

Published image

Pre-built images for linux/amd64 and linux/arm64 are available at:

ghcr.io/Code-Omega-Solutions/mcp-paperless-ngx:latest

Tags follow Semantic Versioning — v1.2.3, 1.2, latest.

---

Getting an API token

In Paperless-ngx, go to Settings → Profile and generate an API token, or use:

curl -X POST http://your-server/api/token/ \
  -d '{"username": "your-user", "password": "your-password"}' \
  -H "Content-Type: application/json"

Connecting from Open WebUI

To use this MCP server with Open WebUI:

1. Open Settings → Functions

2. Click "+" to add a new function

3. Configure the MCP connection:

   • Name: Paperless Assistant (or your preferred name)
   • Type: MCP
   • URL: http://host.docker.internal:8000/mcp
     • If Open WebUI runs in Docker on the same host as mcp-paperless-ngx, use host.docker.internal
     • If running on different hosts, replace with the actual hostname/IP
     • Critical: The port (:8000) and /mcp path are required
   • Auth: None ⚠️
     • Do NOT use "Bearer" — the server authenticates to Paperless internally using credentials from config.toml
     • Open WebUI does not need to provide additional auth tokens
   • Description: (Optional) "Access Paperless-ngx documents"

4. Click Save

5. Test the connection by asking: "Show me documents in my inbox"

Common Issues

• 404 errors: Verify the URL includes /mcp at the end
• Connection refused: Ensure the port :8000 is included and the server is running (uv run mcp-paperless-ngx)
• Authentication errors: Confirm Auth is set to "None", not "Bearer"