Paperless MCP

An MCP (Model Context Protocol) Server for Paperless-ngx, enabling AI assistants and other MCP clients to interact with your Paperless document management system.

Quickstart

Get up and running quickly...

You'll need a paperless instance and an API token (check your profile in the paperless UI).

Run Your Own Instance

You're already running your own Paperless Server, this will be much easier...

Create an environment file:

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

Run with docker:

$ docker run --rm --env-file .env -p 8080:8080  cbinckly/paperless-mcp-go:latest

And you're up and running on http://localhost:8080/mcp.

Run with Claude or any MCP Client

Docker is still easiest, if you've got it, update your MCP config:

{
  "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"
      }
    }
  }
}

Authentication

In most cases, you should run the MCP server using stdio or a local/non-public HTTP server. But if you need an extra layer of security, you can set a token that clients must present to the server.

If you set MCP_AUTH_TOKEN in the environment and are using HTTP transport, the client will have to present it as a bearer token in an authentication header (Authentication: Bearer {MCP_AUTH_TOKEN}) or requests will be rejected.

Features

• Complete Document Management: Search, retrieve, create, update, and delete documents
• Bulk Operations: Efficiently edit multiple documents at once
• Metadata Management: Full CRUD operations for correspondents, document types, tags, storage paths, and custom fields
• Dual Transport Modes: Support for both stdio and HTTP Streaming transports
• Docker Support: Multi-stage Docker builds with security best practices
• Comprehensive Logging: Structured logging with configurable levels
• Type-Safe: Built with Go 1.23 for reliability and performance

Available MCP Tools

Document Tools

• search_documents - Search for documents by text query with pagination
• find_similar_documents - Find documents similar to a given document
• get_document - Retrieve a document by ID with all metadata
• get_document_content - Get the text content of a document
• create_document - Create a new document
• update_document - Update document metadata
• delete_document - Delete a document
• bulk_edit_documents - Perform bulk operations on multiple documents

Correspondent Tools

• list_correspondents - List all correspondents with pagination
• get_correspondent - Get correspondent details by ID
• create_correspondent - Create a new correspondent
• update_correspondent - Update correspondent information
• delete_correspondent - Delete a correspondent

Document Type Tools

• list_document_types - List all document types with pagination
• get_document_type - Get document type details by ID
• create_document_type - Create a new document type
• update_document_type - Update document type information
• delete_document_type - Delete a document type

Tag Tools

• 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

Storage Path Tools

• 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

Custom Field Tools

• 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

Utility Tools

• ping - Test tool that returns pong
• server_info - Get MCP server and Paperless connection information

Prerequisites

• Go 1.23 or later (for building from source)
• A running Paperless-ngx instance
• Paperless-ngx API token
  • You can create (or re-create) an API token by opening the "My Profile" link in the user dropdown found in the web UI and clicking the circular arrow button.
• Docker and Docker Compose (optional, for containerized deployment)

Installation

From Source

git clone https://github.com/cbinckly/paperless-mcp-go.git
cd paperless-mcp-go
go mod download

Using Docker

git clone https://github.com/cbinckly/paperless-mcp-go.git
cd paperless-mcp-go
docker-compose up -d

Configuration

The server is configured using environment variables. Create a .env file based on .env.example:

Variable	Required	Default	Description
PAPERLESS_URL	Yes	-	URL of your Paperless-ngx instance
PAPERLESS_TOKEN	Yes	-	API token for Paperless-ngx authentication
MCP_AUTH_TOKEN	No	-	Optional authentication token for MCP clients
LOG_LEVEL	No	info	Logging level: debug, info, warn, error
MCP_TRANSPORT	No	stdio	Transport mode: stdio or http
MCP_HTTP_PORT	No	8080	HTTP port (only used when MCP_TRANSPORT=http)

Example .env File

PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TOKEN=your_paperless_api_token_here
MCP_AUTH_TOKEN=optional_mcp_auth_token
LOG_LEVEL=info
MCP_TRANSPORT=http
MCP_HTTP_PORT=8080

Building

Build from Source

go build -o paperless-mcp ./cmd/server

Build Docker Image

docker build -t paperless-mcp-go .

Running

Stdio Transport (Default)

Stdio transport is typically used when the MCP server is launched by an MCP client:

# Set environment variables
export PAPERLESS_URL=https://paperless.example.com
export PAPERLESS_TOKEN=your_token_here

# Run the server
./paperless-mcp

HTTP Transport

HTTP transport runs the server as a standalone service using the modern StreamableHTTP protocol:

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

# Run the server
./paperless-mcp

The server will be available at http://localhost:8080.

Using Docker

docker run --env-file .env -p 8080:8080 paperless-mcp-go

Using Docker Compose

docker-compose up -d

Check logs:

docker-compose logs -f

Stop the server:

docker-compose down

Usage Examples

Example 1: Search for Documents

Using the search_documents tool to find documents containing "invoice":

{
  "tool": "search_documents",
  "arguments": {
    "query": "invoice",
    "page": 1,
    "page_size": 10
  }
}

Example 2: Create a Tag

Using the create_tag tool to create a new tag:

{
  "tool": "create_tag",
  "arguments": {
    "name": "Urgent",
    "color": "#ff0000"
  }
}

Example 3: Bulk Edit Documents

Using the bulk_edit_documents tool to add tags to multiple documents:

{
  "tool": "bulk_edit_documents",
  "arguments": {
    "document_ids": [1, 2, 3],
    "add_tags": [5, 6],
    "set_correspondent": 2
  }
}

Deployment

Production Considerations

1. Security:

   • Use HTTPS for Paperless-ngx connections
   • Protect API tokens (use environment variables, not hardcoded values)
   • Run as non-root user (Docker images already configured)
   • Use MCP_AUTH_TOKEN when exposing HTTP transport

2. Performance:

   • Configure appropriate resource limits in docker-compose.yml
   • Monitor memory usage for large document operations
   • Use pagination for list operations

3. Reliability:

   • Enable Docker restart policies (restart: unless-stopped)
   • Monitor health check endpoints
   • Set up logging aggregation

Docker Deployment

The provided Dockerfile uses multi-stage builds for:

• Small image size (< 20MB runtime)
• Static binary with no runtime dependencies
• Non-root user (UID 1000)
• Health checks configured

Resource limits in docker-compose.yml:

• CPU: 1 core maximum, 0.25 core reserved
• Memory: 256MB maximum, 128MB reserved

Adjust these based on your workload.

Monitoring and Logging

• Structured Logging: All logs use structured format (slog)
• Log Levels: Configure via LOG_LEVEL environment variable
• Health Checks: Available at /health endpoint (HTTP mode only)
• Metrics: Check Docker container stats: docker stats paperless-mcp-server

Development

Project Structure

paperless-mcp-go/
├── cmd/
│   └── server/          # Main application entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── mcp/             # MCP server implementation
│   │   ├── server.go    # Server setup and registration
│   │   ├── tools.go     # Tool registration
│   │   ├── *_handlers.go # Tool handler implementations
│   │   └── transport.go # Transport layer
│   └── paperless/       # Paperless API client
│       ├── client.go    # HTTP client and API methods
│       ├── types.go     # Data type definitions
│       └── errors.go    # Error handling
├── Dockerfile
├── docker-compose.yml
└── README.md

Adding New Tools

1. Add API Client Method (internal/paperless/client.go):

   func (c *Client) YourMethod(ctx context.Context, ...) (*Type, error) {
       // Implementation
   }
   

2. Create Handler (appropriate *_handlers.go file):

   func (s *Server) handleYourTool(ctx context.Context, args map[string]interface{}) (interface{}, error) {
       // Implementation
   }
   

3. Register Tool (internal/mcp/tools.go):

   err = s.RegisterTool(Tool{
       Name:        "your_tool",
       Description: "Description of your tool",
       InputSchema: map[string]interface{}{...},
       Handler:     s.handleYourTool,
   })
   

Code Style Guidelines

• Constants: Use descriptive constant names for all magic values
• Logging: Use structured logging with slog (Debug/Info/Error levels)
• Error Handling: Wrap errors with fmt.Errorf("message: %w", err)
• Validation: Validate all inputs in handlers before calling API methods
• Pagination: Support pagination for all list operations

Troubleshooting

Common Issues

Issue: Failed to load configuration: environment variable PAPERLESS_URL is required

• Solution: Ensure all required environment variables are set. Check your .env file.

Issue: Request failed: 401 Unauthorized

• Solution: Verify your PAPERLESS_TOKEN is correct and has appropriate permissions.

Issue: Connection refused when using HTTP transport

• Solution: Ensure MCP_HTTP_PORT is not already in use and firewall allows connections.

Debug Logging

Enable debug logging for detailed information:

export LOG_LEVEL=debug
./paperless-mcp

Debug logs include:

• API request/response details
• Tool invocation parameters
• Detailed error information

Health Check

For HTTP transport mode, check server health:

curl http://localhost:8080/health

Should return health status and server information.

License

See LICENSE file for details.

Links

• Paperless-ngx Documentation
• Model Context Protocol
• MCP Go SDK

---

Note: This is an unofficial community project and is not affiliated with or endorsed by the Paperless-ngx project.