baruchiro/paperless-mcp

An MCP (Model Context Protocol) server for interacting with a Paperless-NGX API server. This server provides tools for managing documents, tags, correspondents, and document types in your Paperless-NGX instance.
Quick Start
Installation
Add these to your MCP config file:
// STDIO mode (recommended for local or CLI use)
// HTTP mode (recommended for Docker or remote use)
3. Get your API token:
1. Log into your Paperless-NGX instance
2. Click your username in the top right
3. Select "My Profile"
4. Click the circular arrow button to generate a new token
4. Replace the placeholders in your MCP config:
- http://your-paperless-instance:8000 with your Paperless-NGX URL
- your-api-token with the token you just generated
- https://your-public-domain.com with your public Paperless-NGX URL (optional, falls back to PAPERLESS_URL)
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| PAPERLESS_URL | Yes | — | Base URL of your Paperless-NGX instance |
| PAPERLESS_API_KEY | Yes | — | API token from your Paperless-NGX profile |
| PAPERLESS_PUBLIC_URL | No | PAPERLESS_URL | Public-facing URL for document links |
| PAPERLESS_API_VERSION | No | 9 | Paperless-ngx REST API version. 9 works on Paperless-ngx v2.x (recent) and v3.x. Paperless-ngx v3.0.0 dropped support for versions below 9, so older defaults now return HTTP 406. If you see HTTP 406 errors, set this to a version your server supports. |
| PAPERLESS_MCP_UPLOAD_PATHS | No | — | Colon-separated list of allowed directories for file_path uploads. **Recommended for security.** Example: /var/uploads:/tmp/scans |
That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.
Example Usage
Here are some things you can ask Claude to do:
- "Show me all documents tagged as 'Invoice'"
- "Search for documents containing 'tax return'"
- "Create a new tag called 'Receipts' with color #FF0000"
- "Download document #123"
- "List all correspondents"
- "Create a new document type called 'Bank Statement'"
Available Tools
Document Operations
list_documents
Get a paginated list of documents with simple filters. Use this for straightforward listing tasks. For full-text queries, structured custom field filtering, or advanced Paperless filters, use query_documents.
Parameters:
- page (optional): Page number
- page_size (optional): Number of documents per page
- search (optional): Simple Paperless search term
- correspondent (optional): Correspondent ID
- document_type (optional): Document type ID
- tag (optional): Tag ID
- storage_path (optional): Storage path ID
- created__date__gte (optional): Created date on or after YYYY-MM-DD
- created__date__lte (optional): Created date on or before YYYY-MM-DD
- ordering (optional): Paperless ordering field
- archive_serial_number (optional): Archive serial number
- archive_serial_number__isnull (optional): Whether the archive serial number is empty
- custom_field_query (optional): Raw JSON-encoded Paperless custom field query string
- custom_fields__icontains (optional): Case-insensitive substring match across custom field values
query_documents
Canonical document query tool. Supports full-text querying, simple Paperless search, custom field filters, and documented /api/documents/ Paperless query parameters.
Parameters:
- page (optional): Page number
- page_size (optional): Number of documents per page
- ordering (optional): Paperless ordering field
- query (optional): Full-text query string
- search (optional): Simple Paperless search term
- more_like_id (optional): Find documents similar to this document ID
- correspondent (optional): Correspondent ID
- document_type (optional): Document type ID
- tag (optional): Tag ID
- storage_path (optional): Storage path ID
- created__date__gte (optional): Created date on or after YYYY-MM-DD
- created__date__lte (optional): Created date on or before YYYY-MM-DD
- custom_field_query (optional): Structured Paperless custom field query using [field_name_or_id, operator, value] leaves or ["AND" | "OR", [clause1, clause2]] groups
- paperless_filters (optional): Additional documented /api/documents/ Paperless query parameters, passed as key/value pairs
get_document
Get a specific document by ID.