# Paperless MCP
An MCP (Model Context Protocol) Server for [Paperless-ngx](https://docs.paperless-ngx.com/), 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:
```env
PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TOKEN=your_paperless_api_token_here
MCP_TRANSPORT=http
MCP_HTTP_PORT=8080
```
Run with docker:
```bash
$ 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:
```json
{
"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](https://docs.paperless-ngx.com/) instance
- [Paperless-ngx API token](https://docs.paperless-ngx.com/api/)
- 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
```bash
git clone https://github.com/cbinckly/paperless-mcp-go.git
cd paperless-mcp-go
go mod download
```
### Using Docker
```bash
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
```env
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
```bash
go build -o paperless-mcp ./cmd/server
```
### Build Docker Image
```bash
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:
```bash
# 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:
```bash
# 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
```bash
docker run --env-file .env -p 8080:8080 paperless-mcp-go
```
### Using Docker Compose
```bash
docker-compose up -d
```
Check logs:
```bash
docker-compose logs -f
```
Stop the server:
```bash
docker-compose down
```
## Usage Examples
### Example 1: Search for Documents
Using the `search_documents` tool to find documents containing "invoice":
```json
{
"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:
```json
{
"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:
```json
{
"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`):
```go
func (c *Client) YourMethod(ctx context.Context, ...) (*Type, error) {
// Implementation
}
```
2. **Create Handler** (appropriate `*_handlers.go` file):
```go
func (s *Server) handleYourTool(ctx context.Context, args map[string]interface{}) (interface{}, error) {
// Implementation
}
```
3. **Register Tool** (`internal/mcp/tools.go`):
```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:
```bash
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:
```bash
curl http://localhost:8080/health
```
Should return health status and server information.
## License
See [LICENSE](LICENSE) file for details.
## Links
- [Paperless-ngx Documentation](https://docs.paperless-ngx.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP Go SDK](https://github.com/mark3labs/mcp-go)
---
**Note**: This is an unofficial community project and is not affiliated with or endorsed by the Paperless-ngx project.
