Enables interaction with Paperless-NGX API servers, supporting document management, tagging, and metadata operations through a natural language interface.
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.
To install Paperless NGX MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @nloui/paperless-mcp --client claudeInstall the MCP server:
npm install -g paperless-mcpAdd 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"]
}
}
}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 generatedThat's it! Now you can ask Claude to help you manage your Paperless-NGX documents.
Here are some things you can ask Claude to do:
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 a specific document by ID.
Parameters: - id: Document ID
get_document({
id: 123
})Full-text search across documents.
Parameters: - query: Search query string
search_documents({
query: "invoice 2024"
})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
})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]
})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"
})Get all tags.
list_tags()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"
})Get all correspondents.
list_correspondents()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"
})Get all document types.
list_document_types()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"
})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
Want to contribute or modify the server? Here's what you need to know:
Install dependencies:
npm installMake your changes to server.js
node server.js http://localhost:8000 your-test-tokenThe server is built with: - litemcp: A TypeScript framework for building MCP servers - zod: TypeScript-first schema validation
This MCP server implements endpoints from the Paperless-NGX REST API. For more details about the underlying API, see the official documentation.
[
{
"description": "Perform bulk operations on documents",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"add_tags": {
"items": {
"type": "number"
},
"type": "array"
},
"correspondent": {
"type": "number"
},
"degrees": {
"type": "number"
},
"delete_originals": {
"type": "boolean"
},
"document_type": {
"type": "number"
},
"documents": {
"items": {
"type": "number"
},
"type": "array"
},
"metadata_document_id": {
"type": "number"
},
"method": {
"enum": [
"set_correspondent",
"set_document_type",
"set_storage_path",
"add_tag",
"remove_tag",
"modify_tags",
"delete",
"reprocess",
"set_permissions",
"merge",
"split",
"rotate",
"delete_pages"
],
"type": "string"
},
"pages": {
"type": "string"
},
"permissions": {
"additionalProperties": false,
"properties": {
"merge": {
"type": "boolean"
},
"owner": {
"type": [
"number",
"null"
]
},
"set_permissions": {
"additionalProperties": false,
"properties": {
"change": {
"additionalProperties": false,
"properties": {
"groups": {
"items": {
"type": "number"
},
"type": "array"
},
"users": {
"items": {
"type": "number"
},
"type": "array"
}
},
"required": [
"users",
"groups"
],
"type": "object"
},
"view": {
"additionalProperties": false,
"properties": {
"groups": {
"items": {
"type": "number"
},
"type": "array"
},
"users": {
"items": {
"type": "number"
},
"type": "array"
}
},
"required": [
"users",
"groups"
],
"type": "object"
}
},
"required": [
"view",
"change"
],
"type": "object"
}
},
"type": "object"
},
"remove_tags": {
"items": {
"type": "number"
},
"type": "array"
},
"storage_path": {
"type": "number"
},
"tag": {
"type": "number"
}
},
"required": [
"documents",
"method"
],
"type": "object"
},
"name": "bulk_edit_documents"
},
{
"description": "Upload a new document to Paperless-NGX",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"archive_serial_number": {
"type": "string"
},
"correspondent": {
"type": "number"
},
"created": {
"type": "string"
},
"custom_fields": {
"items": {
"type": "number"
},
"type": "array"
},
"document_type": {
"type": "number"
},
"file": {
"type": "string"
},
"filename": {
"type": "string"
},
"storage_path": {
"type": "number"
},
"tags": {
"items": {
"type": "number"
},
"type": "array"
},
"title": {
"type": "string"
}
},
"required": [
"file",
"filename"
],
"type": "object"
},
"name": "post_document"
},
{
"description": "List all documents",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"page": {
"type": "number"
},
"page_size": {
"type": "number"
}
},
"type": "object"
},
"name": "list_documents"
},
{
"description": "Get a specific document by ID",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"id": {
"type": "number"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "get_document"
},
{
"description": "Search documents using full-text query",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"query": {
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "search_documents"
},
{
"description": "Download a document by ID",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"id": {
"type": "number"
},
"original": {
"type": "boolean"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "download_document"
},
{
"description": "List all tags",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "list_tags"
},
{
"description": "Create a new tag",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"color": {
"pattern": "^#[0-9A-Fa-f]{6}$",
"type": "string"
},
"match": {
"type": "string"
},
"matching_algorithm": {
"maximum": 4,
"minimum": 0,
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"name": "create_tag"
},
{
"description": "Update an existing tag",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"color": {
"pattern": "^#[0-9A-Fa-f]{6}$",
"type": "string"
},
"id": {
"type": "number"
},
"match": {
"type": "string"
},
"matching_algorithm": {
"maximum": 4,
"minimum": 0,
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"name": "update_tag"
},
{
"description": "Delete a tag",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"id": {
"type": "number"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "delete_tag"
},
{
"description": "Bulk edit tags (set permissions or delete)",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"merge": {
"type": "boolean"
},
"operation": {
"enum": [
"set_permissions",
"delete"
],
"type": "string"
},
"owner": {
"type": "number"
},
"permissions": {
"additionalProperties": false,
"properties": {
"change": {
"additionalProperties": false,
"properties": {
"groups": {
"items": {
"type": "number"
},
"type": "array"
},
"users": {
"items": {
"type": "number"
},
"type": "array"
}
},
"type": "object"
},
"view": {
"additionalProperties": false,
"properties": {
"groups": {
"items": {
"type": "number"
},
"type": "array"
},
"users": {
"items": {
"type": "number"
},
"type": "array"
}
},
"type": "object"
}
},
"required": [
"view",
"change"
],
"type": "object"
},
"tag_ids": {
"items": {
"type": "number"
},
"type": "array"
}
},
"required": [
"tag_ids",
"operation"
],
"type": "object"
},
"name": "bulk_edit_tags"
},
{
"description": "List all correspondents",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "list_correspondents"
},
{
"description": "Create a new correspondent",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"match": {
"type": "string"
},
"matching_algorithm": {
"enum": [
"any",
"all",
"exact",
"regular expression",
"fuzzy"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"name": "create_correspondent"
},
{
"description": "Bulk edit correspondents (set permissions or delete)",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"correspondent_ids": {
"items": {
"type": "number"
},
"type": "array"
},
"merge": {
"type": "boolean"
},
"operation": {
"enum": [
"set_permissions",
"delete"
],
"type": "string"
},
"owner": {
"type": "number"
},
"permissions": {
"additionalProperties": false,
"properties": {
"change": {
"additionalProperties": false,
"properties": {
"groups": {
"items": {
"type": "number"
},
"type": "array"
},
"users": {
"items": {
"type": "number"
},
"type": "array"
}
},
"type": "object"
},
"view": {
"additionalProperties": false,
"properties": {
"groups": {
"items": {
"type": "number"
},
"type": "array"
},
"users": {
"items": {
"type": "number"
},
"type": "array"
}
},
"type": "object"
}
},
"required": [
"view",
"change"
],
"type": "object"
}
},
"required": [
"correspondent_ids",
"operation"
],
"type": "object"
},
"name": "bulk_edit_correspondents"
},
{
"description": "List all document types",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "list_document_types"
},
{
"description": "Create a new document type",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"match": {
"type": "string"
},
"matching_algorithm": {
"enum": [
"any",
"all",
"exact",
"regular expression",
"fuzzy"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"name": "create_document_type"
},
{
"description": "Bulk edit document types (set permissions or delete)",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"document_type_ids": {
"items": {
"type": "number"
},
"type": "array"
},
"merge": {
"type": "boolean"
},
"operation": {
"enum": [
"set_permissions",
"delete"
],
"type": "string"
},
"owner": {
"type": "number"
},
"permissions": {
"additionalProperties": false,
"properties": {
"change": {
"additionalProperties": false,
"properties": {
"groups": {
"items": {
"type": "number"
},
"type": "array"
},
"users": {
"items": {
"type": "number"
},
"type": "array"
}
},
"type": "object"
},
"view": {
"additionalProperties": false,
"properties": {
"groups": {
"items": {
"type": "number"
},
"type": "array"
},
"users": {
"items": {
"type": "number"
},
"type": "array"
}
},
"type": "object"
}
},
"required": [
"view",
"change"
],
"type": "object"
}
},
"required": [
"document_type_ids",
"operation"
],
"type": "object"
},
"name": "bulk_edit_document_types"
}
]