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.
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 @baruchiro/paperless-mcp --client claude
Add these to your MCP config file:
// STDIO mode (recommended for local or CLI use)
"paperless": {
"command": "npx",
"args": [
"-y",
"@baruchiro/paperless-mcp@latest",
],
"env": {
"PAPERLESS_URL": "http://your-paperless-instance:8000",
"PAPERLESS_API_KEY": "your-api-token"
}
}
// HTTP mode (recommended for Docker or remote use)
"paperless": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/baruchiro/paperless-mcp:latest",
],
"env": {
"PAPERLESS_URL": "http://your-paperless-instance:8000",
"PAPERLESS_API_KEY": "your-api-token"
}
}
Get your API 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:
list_documents({
page: 1,
page_size: 25
})
Get a specific document by ID.
Parameters:
get_document({
id: 123
})
Full-text search across documents.
Parameters:
search_documents({
query: "invoice 2024"
})
Download a document file by ID.
Parameters:
download_document({
id: 123,
original: false
})
Perform bulk operations on multiple documents.
Parameters:
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:
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:
create_tag({
name: "Invoice",
color: "#ff0000",
match: "invoice",
matching_algorithm: "fuzzy"
})
Get all correspondents.
list_correspondents()
Create a new correspondent.
Parameters:
create_correspondent({
name: "ACME Corp",
match: "ACME",
matching_algorithm: "fuzzy"
})
Get all document types.
list_document_types()
Create a new document type.
Parameters:
create_document_type({
name: "Invoice",
match: "invoice total amount due",
matching_algorithm: "any"
})
The server will show clear error messages if:
Want to contribute or modify the server? Here’s what you need to know:
npm install
node server.js http://localhost:8000 your-test-token
The server is built with:
This MCP server implements endpoints from the Paperless-NGX REST API. For more details about the underlying API, see the official documentation.
The MCP server can be run in two modes:
This is the default mode. The server communicates over stdio, suitable for CLI and direct integrations.
npm run start -- <baseUrl> <token>
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
POST /mcp
on the specified port./mcp
will return 405 Method Not Allowed.This project is a fork of nloui/paperless-mcp. Many thanks to the original author for their work. Contributions and improvements may be returned upstream.