An MCP 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.
Manage task backlogs using a file-based JSON storage system.
A CalDAV MCP server to expose calendar operations as tools for AI assistants.
Provides direct access to your Bear notes database for comprehensive note management, bypassing standard API limitations.
A comprehensive travel planning server for flight search, accommodation booking, currency exchange, and weather forecasting.
Guides problem-solving by breaking down complex problems and recommending the best MCP tools for each step.
Read, create, update and delete Google Keep notes.
Interact with Ramp's Developer API to run analysis on your spend and gain insights leveraging LLMs
AnkiConnect MCP server for interacting with Anki via AnkiConnect.
Manage and interact with Google Calendar events using the Google Calendar API.
A spellchecker and grammar checker for developers, requiring a Hyperspell token for authentication.