bulk_edit_correspondents
Bulk edit correspondents. ⚠️ WARNING: 'delete' operation permanently removes correspondents from the entire system.
LABSCO SUMMARY
You stop opening the Paperless web UI to file one scan.
Tags, correspondents and document types each carry a matching pattern and algorithm, so a classification you fix once by hand keeps applying to everything that arrives afterwards. The destructive tools are labelled as destructive in their own descriptions — deleting a tag or a custom field strips it from every document that uses it, and the delete method on bulk_edit_documents asks for confirmation before it runs.
What it is
A full-surface client for a Paperless-NGX instance: 44 tools covering documents, tags, correspondents, document types, custom fields, document notes, and the mail accounts and rules that pull attachments in.
What you get
- Documents found two ways — list_documents for plain filters (correspondent, type, tag, storage path, creation date, archive serial number), query_documents for full-text plus structured custom-field conditions written as [field_name_or_id, operator, value] leaves joined by AND and OR
- more_like_id on query_documents, so you can hand it one document and ask what else looks like it
- get_document_content fetches the text separately from the metadata, so listings stay small until you ask to actually read one
- post_document uploads either base64 content or a file already sitting on the server's filesystem, up to 100MB either way
- list_document_notes, create_document_note and delete_document_note keep a running history on the document itself — paid, disputed, filed — instead of in a spreadsheet next to it
- bulk_edit_documents applies one decision to a set: tags added or removed, correspondent, type, storage path and custom fields reassigned, permissions set, pages rotated, split, deleted or merged
- Tags, correspondents and document types created with their own matching pattern and algorithm, so documents arriving next month get classified without you
- create_custom_field defines a field by data type — string, url, date, boolean, integer, float, monetary, documentlink or select — with monetary values written as a currency-code prefix such as USD10.00
- Mail rules created and patched against a mail account, filtered on sender, recipient, subject, body or attachment filename, and process_mail_account runs the ingest on demand
- download_document and get_document_thumbnail return a paperless:// resource URI you read to get the bytes, so a file never has to travel through the chat as base64
Requirements
A Paperless-NGX instance at PAPERLESS_URL and a profile API token in PAPERLESS_API_KEY. Run it over stdio with npx from @baruchiro/paperless-mcp, or as the ghcr.io/baruchiro/paperless-mcp container when the server is remote. PAPERLESS_MCP_UPLOAD_PATHS is worth setting — it limits which directories a file_path upload may read — and PAPERLESS_API_VERSION defaults to 9, which suits recent 2.x and 3.x servers; an HTTP 406 back means yours wants a different one.
Setup effort
One command plus a key — npx -y @baruchiro/paperless-mcp@latest, then supply credentials
USE CASES
01
Finding the document you only half remember
Describe it the way it comes to mind — the company, roughly when, the word you are sure was on it — and it narrows by correspondent, tag and date before falling back to the full-text engine, then reads back the text of the one that matches.
02
Filing a scan that just landed
Hand it a file and say what it is. It uploads the document, sets the title, correspondent, type and tags in the same call, and creates any of those that do not exist yet.
03
Cleaning up a year of untagged documents
Pull the set that is missing what it should have, then apply the fix to all of them at once — tags added and removed, correspondent and type reassigned — rather than one document at a time in the browser.
04
Keeping a paper trail on an invoice
Record what happened to a document on the document: paid on this date from this account, disputed, waiting on a credit note. The notes stay with the file and come back the next time anyone reads it.
05
Making next month's post file itself
Set up the classification once — a tag, a correspondent and a document type, each with the pattern that recognises it — so documents arriving later are sorted on the way in instead of piling up as inbox items.
06
Pulling invoices straight out of a mailbox
Point a rule at one of your Paperless mail accounts, filter it down to the sender and the attachment names you care about, then run the ingest on demand instead of waiting for the next scheduled pass.
07
Tracking a field Paperless does not have
Add the field you actually need — an invoice number, an amount, a renewal date — with the right data type, then query documents by conditions on it, including the ones where it is still empty.
44 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
bulk_edit_custom_fields
Bulk edit custom fields. ⚠️ WARNING: 'delete' operation permanently removes custom fields from the entire system.
bulk_edit_document_types
Bulk edit document types. ⚠️ WARNING: 'delete' operation permanently removes document types from the entire system.
bulk_edit_documents
Perform bulk operations on multiple documents. Note: 'remove_tag' removes a tag from specific documents (tag remains in system), while 'delete_tag' permanently deletes a tag from the entire system. ⚠️ WARNING: 'delete' method permanently deletes documents and requires confirmation.
bulk_edit_tags
Bulk edit tags. ⚠️ WARNING: 'delete' operation permanently removes tags from the entire system. Use with caution.
create_correspondent
Create a new correspondent with optional matching pattern and algorithm for automatic document assignment.
create_custom_field
Create a new custom field with a specified data type (string, url, date, boolean, integer, float, monetary, documentlink, or select). For monetary fields, values must use currency code prefix format (e.g., USD10.00, GBP123.45) — NOT trailing symbol format (e.g., 10.00$).
create_document_note
Add a note to a document. Use this to record an audit trail or progress note directly on the document. Returns the document's full list of notes after the note is added.
create_document_type
Create a new document type with optional matching pattern and algorithm for automatic document classification.
create_mail_rule
Create a Paperless mail rule. Use list_mail_accounts first to choose account. Prefer attachment-only rules for invoices unless the full mail must be archived.
create_tag
Create a new tag with optional color, matching pattern, and matching algorithm for automatic document tagging.
delete_correspondent
⚠️ DESTRUCTIVE: Permanently delete a correspondent from the entire system. This will affect ALL documents that use this correspondent.
delete_custom_field
⚠️ DESTRUCTIVE: Permanently delete a custom field from the entire system. This will remove the field from ALL documents that use it.
delete_document_note
⚠️ DESTRUCTIVE: Permanently delete a single note from a document by its note ID. This operation is irreversible. Returns the document's remaining notes.
delete_document_type
⚠️ DESTRUCTIVE: Permanently delete a document type from the entire system. This will affect ALL documents that use this type.
delete_mail_rule
Delete one Paperless mail rule. This changes future mail ingestion behavior but does not delete documents.
delete_tag
⚠️ DESTRUCTIVE: Permanently delete a tag from the entire system. This will remove the tag from ALL documents that use it. Use with extreme caution.
download_document
Download a document file by ID. Returns a paperless:// resource URI; read the resource to fetch the file content.
get_correspondent
Get a specific correspondent by ID with full details including matching rules.
get_custom_field
Get a specific custom field by ID with full details including data type and extra configuration.
get_document
Get a specific document by ID with full details including correspondent, document type, tags, and custom fields. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed.
get_document_content
Get the text content of a specific document by ID. Use this when you need to read or analyze the actual document text.
get_document_thumbnail
Get a document thumbnail (image preview) by ID. Returns a paperless:// resource URI; read the resource to fetch the image content.
get_document_type
Get a specific document type by ID with full details including matching rules.
get_mail_account
Get one Paperless mail account by ID. Password/token fields are redacted if the server returns them.
get_mail_rule
Get one Paperless mail rule by ID.
list_correspondents
List all correspondents with optional filtering and pagination. Correspondents represent entities that send or receive documents.
list_custom_fields
List all custom fields. IMPORTANT: When a user query may refer to a custom field, you should fetch all custom fields up front (with a large enough page_size), cache them for the session, and search locally for matches by name before making further API calls. This reduces redundant requests and handles ambiguity efficiently.
list_document_notes
List all notes attached to a document. Notes are free-text comments on a document and are the natural place for an audit trail (e.g. "invoice paid on X from account Y") or progress notes on an action item.
list_document_types
List all document types. IMPORTANT: When a user query may refer to a document type or tag, you should fetch all document types and all tags up front (with a large enough page_size), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.
list_documents
List and filter documents with pagination and common Paperless filters such as title search, correspondent, document type, tag, storage path, creation date, archive serial number, and simple custom field filters. Use 'query_documents' for full-text query, structured custom field conditions, or advanced documented /api/documents/ query parameters. IMPORTANT: For queries like 'the last 3 contributions' or when searching by tag, correspondent, document type, or storage path, first use the relevant lookup tool to find the correct ID. Note: Document content is excluded from results by default. Use 'get_document_content' when you need the document text.
list_mail_accounts
List Paperless mail accounts for selecting the account ID needed by mail rules. Does not expose account passwords.
list_mail_rules
List Paperless mail rules with optional pagination.
list_tags
List all tags. IMPORTANT: When a user query may refer to a tag or document type, you should fetch all tags and all document types up front (with a large enough page_size), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.
post_document
Upload a new document to Paperless-NGX with optional metadata like title, correspondent, document type, tags, and custom fields. Provide either 'file' (base64-encoded content) or 'file_path' (absolute path to a file on the server's filesystem). Using file_path avoids base64 encoding overhead for large files. SECURITY: When using file_path, set PAPERLESS_MCP_UPLOAD_PATHS environment variable to restrict uploads to specific directories (colon-separated paths).
process_mail_account
Manually run Paperless mail processing for one account. This can consume matching mails according to enabled Paperless mail rules.
query_documents
Query documents using the full-text query engine plus structured Paperless filters. Use this for complex filtering, custom field conditions, or any documented /api/documents/ query parameters that are not exposed as first-class arguments. Prefer the dedicated top-level arguments where available. custom_field_query supports [field_name_or_id, operator, value] leaves or ['AND'|'OR', [clause1, clause2]] groups. Note: Document content is excluded from results by default. Use 'get_document_content' when you need the document text.
search_documents
Deprecated compatibility wrapper for full-text document search. Use 'query_documents' with the 'query' argument for new integrations. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed.
update_correspondent
Update an existing correspondent's name, matching pattern, or matching algorithm.
update_custom_field
Update an existing custom field's name, data type, or extra configuration data.
update_document
Update a specific document with new values (title, correspondent, document type, storage path, tags, custom fields, and more). Top-level fields you omit are left unchanged. IMPORTANT: custom_fields is the exception — see its parameter description; it replaces the document's entire custom-field set.
update_document_type
Update an existing document type's name, matching pattern, or matching algorithm.
update_mail_rule
Patch an existing Paperless mail rule. Only supplied fields are changed.
update_tag
Update an existing tag's name, color, matching pattern, or matching algorithm.
BEFORE YOU INSTALL
What to know first
Tools you get
44 tools when we connected. The documentation lists only 31; the undocumented ones include update_document, get_document_content and the update, delete and bulk-edit tools for tags, correspondents and document types.
Requires
- npx on PATH
- A running Paperless-NGX instance, with its base URL in PAPERLESS_URL
- PAPERLESS_API_KEY in your environment
CONTEXT COST
Moderate Standing cost
Rated by the size of the 44 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y @baruchiro/paperless-mcp@latestMCP Clients
Any MCP client — stdio
ANY MCP CLIENT — STDIO · JSON
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": [
"-y",
"@baruchiro/paperless-mcp@latest"
],
"env": {
"PAPERLESS_URL": "http://<YOUR_PAPERLESS_INSTANCE>:8000",
"PAPERLESS_API_KEY": "<YOUR_PAPERLESS_API_KEY>",
"PAPERLESS_PUBLIC_URL": "<YOUR_PAPERLESS_PUBLIC_URL>"
}
}
}
}http://<YOUR_PAPERLESS_INSTANCE>:8000 is your Paperless-NGX address, and <YOUR_PAPERLESS_API_KEY> is a token from My Profile in Paperless (the circular-arrow button generates one). PAPERLESS_PUBLIC_URL is optional: it is the public address used in document links, and without it links use PAPERLESS_URL.
