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:
Manual Installation
- Install the MCP server:
- 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:For Claude desktop app, edit
~/Library/Application Support/Claude/claude_desktop_config.json:- Get your API token:
- Replace the placeholders in your MCP config:
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 all documents.
Parameters:
- page (optional): Page number
- page_size (optional): Number of documents per page
get_document
Get a specific document by ID.
Parameters:
- id: Document ID
search_documents
Full-text search across documents.
Parameters:
- query: Search query string
download_document
Download a document file by ID.
Parameters:
- id: Document ID
- original (optional): If true, downloads original file instead of archived version
bulk_edit_documents
Perform bulk operations on multiple documents.
Parameters:
- documents: Array of document IDs
- method: One of:
- Additional parameters based on method:
Examples:
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
Tag Operations
list_tags
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"
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"
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"
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:
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.
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:
Manual Installation
- Install the MCP server:
- 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:For Claude desktop app, edit
~/Library/Application Support/Claude/claude_desktop_config.json:- Get your API token:
- Replace the placeholders in your MCP config:
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 all documents.
Parameters:
- page (optional): Page number
- page_size (optional): Number of documents per page
get_document
Get a specific document by ID.
Parameters:
- id: Document ID
search_documents
Full-text search across documents.
Parameters:
- query: Search query string
download_document
Download a document file by ID.
Parameters:
- id: Document ID
- original (optional): If true, downloads original file instead of archived version
bulk_edit_documents
Perform bulk operations on multiple documents.
Parameters:
- documents: Array of document IDs
- method: One of:
- Additional parameters based on method:
Examples:
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
Tag Operations
list_tags
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"
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"
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"
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:
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.