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

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
Performance:
- Configure appropriate resource limits in docker-compose.yml
- Monitor memory usage for large document operations
- Use pagination for list operations
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

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

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

Create Handler (appropriate *_handlers.go file):

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

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

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

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.

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

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
Performance:
- Configure appropriate resource limits in docker-compose.yml
- Monitor memory usage for large document operations
- Use pagination for list operations
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

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

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

Create Handler (appropriate *_handlers.go file):

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

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

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

paperless-mcp-go

Paperless MCP

Quickstart

Run Your Own Instance

Run with Claude or any MCP Client

Authentication

Features

Available MCP Tools

Document Tools

Correspondent Tools

Document Type Tools

Tag Tools

Storage Path Tools

Custom Field Tools

Utility Tools

Prerequisites

Installation

From Source

Using Docker

Configuration

Example .env File

Building

Build from Source

Build Docker Image

Running

Stdio Transport (Default)

HTTP Transport

Using Docker

Using Docker Compose

Usage Examples

Example 1: Search for Documents

Example 2: Create a Tag

Example 3: Bulk Edit Documents

Deployment

Production Considerations

Docker Deployment

Monitoring and Logging

Development

Project Structure

Adding New Tools

Code Style Guidelines

Troubleshooting

Common Issues

Debug Logging

Health Check

License

Links

Paperless MCP

Quickstart

Run Your Own Instance

Run with Claude or any MCP Client

Authentication

Features

Available MCP Tools

Document Tools

Correspondent Tools

Document Type Tools

Tag Tools

Storage Path Tools

Custom Field Tools

Utility Tools

Prerequisites

Installation

From Source

Using Docker

Configuration

Example .env File

Building

Build from Source

Build Docker Image

Running

Stdio Transport (Default)

HTTP Transport

Using Docker

Using Docker Compose

Usage Examples

Example 1: Search for Documents

Example 2: Create a Tag

Example 3: Bulk Edit Documents

Deployment

Example `.env` File

Example `.env` File