Paperless-NGX MCP Server
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
Installing via Smithery
To install Paperless NGX MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @nloui/paperless-mcp --client claude
Manual Installation
- Install the MCP server:
npm install -g paperless-mcp
- Add it to your Claude's MCP configuration:
For VSCode extension, edit ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json:
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
}
}
}
For Claude desktop app, edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
}
}
}
- Get your API token:
- Log into your Paperless-NGX instance
- Click your username in the top right
- Select "My Profile"
- Click the circular arrow button to generate a new token
- Replace the placeholders in your MCP config:
http://your-paperless-instance:8000 with your Paperless-NGX URLyour-api-token with the token you just generated
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'"
Document Operations
list_documents
Get a paginated list of all documents.
Parameters:
- page (optional): Page number
- page_size (optional): Number of documents per page
list_documents({
page: 1,
page_size: 25
})
get_document
Get a specific document by ID.
Parameters:
get_document({
id: 123
})
search_documents
Full-text search across documents.
Parameters:
- query: Search query string
search_documents({
query: "invoice 2024"
})
download_document
Download a document file by ID.
Parameters:
- id: Document ID
- original (optional): If true, downloads original file instead of archived version
download_document({
id: 123,
original: false
})
bulk_edit_documents
Perform bulk operations on multiple documents.
Parameters:
- documents: Array of document IDs
- method: One of:
- set_correspondent: Set correspondent for documents
- set_document_type: Set document type for documents
- set_storage_path: Set storage path for documents
- add_tag: Add a tag to documents
- remove_tag: Remove a tag from documents
- modify_tags: Add and/or remove multiple tags
- delete: Delete documents
- reprocess: Reprocess documents
- set_permissions: Set document permissions
- merge: Merge multiple documents
- split: Split a document into multiple documents
- rotate: Rotate document pages
- delete_pages: Delete specific pages from a document
- Additional parameters based on method:
- correspondent: ID for set_correspondent
- document_type: ID for set_document_type
- storage_path: ID for set_storage_path
- tag: ID for add_tag/remove_tag
- add_tags: Array of tag IDs for modify_tags
- remove_tags: Array of tag IDs for modify_tags
- permissions: Object for set_permissions with owner, permissions, merge flag
- metadata_document_id: ID for merge to specify metadata source
- delete_originals: Boolean for merge/split
- pages: String for split "[1,2-3,4,5-7]" or delete_pages "[2,3,4]"
- degrees: Number for rotate (90, 180, or 270)
Examples:
// Add a tag to multiple documents
bulk_edit_documents({
documents: [1, 2, 3],
method: "add_tag",
tag: 5
})
// Set correspondent and document type
bulk_edit_documents({
documents: [4, 5],
method: "set_correspondent",
correspondent: 2
})
// Merge documents
bulk_edit_documents({
documents: [6, 7, 8],
method: "merge",
metadata_document_id: 6,
delete_originals: true
})
// Split document into parts
bulk_edit_documents({
documents: [9],
method: "split",
pages: "[1-2,3-4,5]"
})
// Modify multiple tags at once
bulk_edit_documents({
documents: [10, 11],
method: "modify_tags",
add_tags: [1, 2],
remove_tags: [3, 4]
})
post_document
Upload a new document to Paperless-NGX.
Parameters:
- file: Base64 encoded file content
- filename: Name of the file
- title (optional): Title for the document
- created (optional): DateTime when the document was created (e.g. "2024-01-19" or "2024-01-19 06:15:00+02:00")
- correspondent (optional): ID of a correspondent
- document_type (optional): ID of a document type
- storage_path (optional): ID of a storage path
- tags (optional): Array of tag IDs
- archive_serial_number (optional): Archive serial number
- custom_fields (optional): Array of custom field IDs
post_document({
file: "base64_encoded_content",
filename: "invoice.pdf",
title: "January Invoice",
created: "2024-01-19",
correspondent: 1,
document_type: 2,
tags: [1, 3],
archive_serial_number: "2024-001"
})
Tag Operations
Get all tags.
create_tag
Create a new tag.
Parameters:
- name: Tag name
- color (optional): Hex color code (e.g. "#ff0000")
- match (optional): Text pattern to match
- matching_algorithm (optional): One of "any", "all", "exact", "regular expression", "fuzzy"
create_tag({
name: "Invoice",
color: "#ff0000",
match: "invoice",
matching_algorithm: "fuzzy"
})
Correspondent Operations
list_correspondents
Get all correspondents.
create_correspondent
Create a new correspondent.
Parameters:
- name: Correspondent name
- match (optional): Text pattern to match
- matching_algorithm (optional): One of "any", "all", "exact", "regular expression", "fuzzy"
create_correspondent({
name: "ACME Corp",
match: "ACME",
matching_algorithm: "fuzzy"
})
Document Type Operations
list_document_types
Get all document types.
create_document_type
Create a new document type.
Parameters:
- name: Document type name
- match (optional): Text pattern to match
- matching_algorithm (optional): One of "any", "all", "exact", "regular expression", "fuzzy"
create_document_type({
name: "Invoice",
match: "invoice total amount due",
matching_algorithm: "any"
})
Error Handling
The server will show clear error messages if:
- The Paperless-NGX URL or API token is incorrect
- The Paperless-NGX server is unreachable
- The requested operation fails
- The provided parameters are invalid
Development
Want to contribute or modify the server? Here's what you need to know:
- Clone the repository
- Install dependencies:
- Make your changes to server.js
- Test locally:
node server.js http://localhost:8000 your-test-token
The server is built with:
- litemcp: A TypeScript framework for building MCP servers
- zod: TypeScript-first schema validation
API Documentation
This MCP server implements endpoints from the Paperless-NGX REST API. For more details about the underlying API, see the official documentation.
Running the MCP Server
The MCP server can be run in two modes:
1. stdio (default)
This is the default mode. The server communicates over stdio, suitable for CLI and direct integrations.
npm run start -- <baseUrl> <token>
2. HTTP (Streamable HTTP Transport)
To run the server as an HTTP service, use the --http flag. You can also specify the port with --port (default: 3000). This mode requires Express to be installed (it is included as a dependency).
npm run start -- <baseUrl> <token> --http --port 3000
- The MCP API will be available at
POST /mcp on the specified port. - Each request is handled statelessly, following the StreamableHTTPServerTransport pattern.
- GET and DELETE requests to
/mcp will return 405 Method Not Allowed.