mcp-paperless-ngx

Mark finished or failed tasks as acknowledged so they stop showing in the UI.

Download several documents as one zip archive, written to the download directory. Returns the archive path, not its contents.

Apply one operation to many documents at once. Far cheaper than looping update_document, and the only way to add or remove individual tags without replacing the whole tag list. Methods: set_correspondent, set_document_type, set_storage_path, add_tag, remove_tag, modify_tags, modify_custom_fields, set_permissions, reprocess, delete, rotate, merge, split, delete_pages, edit_pdf, remove_password. The destructive methods (delete, delete_pages, split/merge with delete_originals) need explicit user confirmation first.

Delete or set permissions on many tags, correspondents, document types or storage paths at once. Deletion here is permanent — confirm with the user before calling it.

Create a new correspondent. Check list_correspondents first: near-duplicate entries are hard to merge later.

Define a new custom field. The data type cannot be changed afterwards, so pick it deliberately.

Attach a free-text note to a document. Use this to record context that belongs with the document rather than in the conversation — why it was kept, what was agreed, what to do next.

Create a new document type. Check list_document_types first: near-duplicate entries are hard to merge later.

Save a filter preset that shows up in the user's Paperless sidebar. filter_rules use the web UI's numeric rule types — copy the shape from an existing view via get_saved_view rather than guessing.

Create a public, unauthenticated URL for a document. Anyone holding the link can read the document until it expires. Always confirm with the user before creating one, and set an expiration unless they explicitly asked for a permanent link.

Publish several documents behind one public link. Same warning as create_share_link: this is publicly reachable without authentication. Confirm first and prefer a finite expiration.

Create a new storage path. Check list_storage_paths first: near-duplicate entries are hard to merge later.

Create a new tag. Check list_tags first: near-duplicate entries are hard to merge later.

Create an automation rule. Workflows run automatically against future documents, so a mistake here silently mis-files everything that arrives afterwards. Read an existing workflow with get_workflow to copy the exact shape, and confirm the rule with the user before creating it. Trigger object. type: 1=consumption started, 2=document added, 3=document updated, 4=scheduled. Common fields: sources (1=consume folder, 2=API upload, 3=mail fetch), filter_filename, filter_path, filter_mailrule, match + matching_algorithm, filter_has_tags / filter_has_all_tags / filter_has_not_tags, filter_has_any_correspondents, filter_has_any_document_types, filter_custom_field_query, and for scheduled triggers schedule_offset_days, schedule_is_recurring, schedule_recurring_interval_days, schedule_date_field (added|created|modified|custom_field). Action object. type: 1=assignment, 2=removal, 3=email, 4=webhook, 5=..., 6=... Assignment actions use assign_title, assign_tags, assign_correspondent, assign_document_type, assign_storage_path, assign_owner, assign_view_users/groups, assign_custom_fields. Removal actions use the remove_* counterparts. Email and webhook actions nest their own config object.

Permanently delete a correspondent. Documents are not deleted, but they lose this assignment and it cannot be restored. Confirm with the user first.

Delete a custom field definition and every value stored in it, across all documents. This cannot be undone — confirm with the user, and check document_count first.

Move a document to the trash. It stays recoverable until the trash is emptied or the retention period expires. Always confirm with the user before deleting anything.

Remove a note from a document. Not recoverable.

Move several documents to the trash at once. Recoverable until the trash is emptied. Requires explicit user confirmation — list what will be deleted before calling this.

Permanently delete a document type. Documents are not deleted, but they lose this assignment and it cannot be restored. Confirm with the user first.

Remove a saved view. Documents are unaffected.

Revoke a share link immediately. Anyone still holding the URL loses access at once; the document itself is untouched.

Revoke a share link bundle immediately. Every document in the bundle stops being publicly reachable; the documents themselves are untouched.

Permanently delete a storage path. Documents are not deleted, but they lose this assignment and it cannot be restored. Confirm with the user first.

Permanently delete a tag. Documents are not deleted, but they lose this assignment and it cannot be restored. Confirm with the user first.

Delete an automation rule permanently. Consider update_workflow with enabled:false instead.

Save a document's file to disk on the machine running this MCP server and return the path. Files are written to PAPERLESS_DOWNLOAD_DIR (defaults to the system temp directory). The bytes are deliberately not returned inline — a PDF as base64 would consume the entire context.

Reorder, rotate, remove or split out pages of a single document, producing a new document. operations is a list of page instructions; each entry names a source page and what to do with it. Consult the Paperless API docs for the exact operation shape before using this.

Send one or more documents by email from the Paperless instance. This sends real mail to real people — only call it after the user has confirmed the recipients, subject and body.

Permanently destroy trashed documents. There is no recovery after this — the files are gone. Never call this without the user explicitly asking for it in the current conversation, and list what is in the trash first.

Tasks executing right now. Tells you whether the instance is busy.

Fetch a single correspondent by ID, with all fields.

One custom field definition including its select options, if any.

Fetch one document's metadata by ID: title, correspondent, type, tags, dates, custom fields, notes and available versions. Does not include the OCR text unless include_content is set.

Suggestions from the instance's configured LLM backend (Paperless-ngx 3.x, only if AI features are enabled server-side). Returns 404 or an error when AI is disabled — that is expected, not a bug.

Return the OCR/extracted text of one document. Deliberately a separate tool: this is the most expensive thing you can pull from Paperless, so fetch it only for documents you have already narrowed down. Supports offset/limit for long documents.

Audit trail of changes to a document — who changed which field, and when. Requires audit logging to be enabled on the instance. Returns the most recent entries first; raise limit to see further back.

Technical file metadata for a document: checksums, byte sizes, MIME type, stored filename, whether an archived PDF/A version exists, and embedded PDF metadata. Not the Paperless tags/correspondent — use get_document for those.

Paperless' own suggestions for a document — correspondents, tags, document types and dates its classifier considers likely. Useful as a starting point when triaging, but the suggestions are only as good as the trained model; verify before applying.

Return the document's thumbnail image inline so it can actually be looked at. Useful for confirming what a document is without reading its whole OCR text.

Fetch a single document type by ID, with all fields.

One compact snapshot of all tags, correspondents, document types and storage paths with their IDs and document counts. Cheaper than four separate list calls and the right first step before filing or triaging documents.

The next free archive serial number, for filing a physical document alongside its scan.

The latest Paperless-ngx release, and whether an update is available.

One saved view including its filter rules, so you can reproduce it as a search.

For a set of document IDs, return how many of them carry each tag, correspondent, document type and storage path. Answers 'what is in this pile?' in one call instead of fetching every document.

Instance health: Paperless version, database and index status, whether Redis and the task workers are reachable, and whether the search index is up to date.

Totals for the archive: document count, inbox count, characters, file type breakdown. A cheap orientation call at the start of a session.

Fetch a single storage path by ID, with all fields.

Fetch a single tag by ID, with all fields.

One background task by database ID, including its result. Use this to find out whether an upload or merge actually succeeded.

One workflow with its full trigger and action definitions.

Search across every object type at once — documents, tags, correspondents, document types, storage paths, saved views, users, groups, mail rules, custom fields and workflows. Returns at most three hits per type, so use it to locate things by name when you do not yet know which kind of object you are looking for. For document searches, search_documents is better.

List correspondents. A correspondent is the sender or counterparty a document came from. Returns id, name and document_count for each. Call this before creating anything — reusing an existing correspondent is almost always correct.

Custom fields defined on this instance, with their IDs, data types and how many documents use them. You need the IDs before you can read or write custom field values on a document.

Notes attached to a document, with authors and timestamps. Notes hold context the OCR text does not contain — worth reading before drawing conclusions about a document.

Existing share links for one document — check this before creating another.

List document types. A document type says what kind of document it is (invoice, contract, payslip). Returns id, name and document_count for each. Call this before creating anything — reusing an existing document type is almost always correct.

Saved views are the filter presets the user built in the Paperless web UI. Reading them is the fastest way to learn how this person actually organises their archive — check here before inventing your own filters.

Share link bundles (Paperless-ngx 3.x) expose several documents behind a single public link.

Every share link on the instance, with its slug, target document and expiry. Share links are publicly reachable without login — treat this list as security-relevant.

List storage paths. A storage path is a filename template controlling where Paperless stores the file on disk. Returns id, name and document_count for each. Call this before creating anything — reusing an existing storage path is almost always correct.

List tags. Tags are the primary way documents are categorised, and can be nested via parent. Returns id, name and document_count for each. Call this before creating anything — reusing an existing tag is almost always correct.

Background tasks — consumption, merges, reprocessing — with their state and result. This is where an upload's outcome shows up, including the ID of the document it created.

Documents in the trash, with the date each was deleted and when it will be purged for good.

Action definitions across all workflows. Useful for auditing what gets assigned automatically.

Automation rules on this instance, each with its triggers and actions inlined. Read these before changing filing behaviour — a workflow may already be doing what the user is asking you to do by hand.

Trigger definitions across all workflows. Useful for auditing what fires when.

Merge several documents into one new PDF, in the order given. The originals stay unless delete_originals is set. Runs asynchronously — poll the returned task with get_task.

Decrypt password-protected PDFs so Paperless can OCR them. The password is sent to your Paperless instance over its API; only use it against an instance you control.

Re-run OCR and the archive generation for the given documents, e.g. after changing OCR settings. Queued asynchronously; the documents keep their metadata.

Bring deleted documents back. The safe counterpart to delete_document.

Rotate every page of the given documents clockwise by 90, 180 or 270 degrees.

Completions for a partial search term, ranked by importance in the full-text index. Helpful when the user's spelling of a name or term may not match what is in the archive.

Find documents by full-text search, metadata filters, or both. This is the main entry point for every 'which documents ...' question. Returns a compact summary per document (id, title, IDs of correspondent/type/tags, dates) — NOT the OCR text, which would flood the context. Use get_document_content for the text of a specific document.

Render a storage path template against an existing document to see the resulting file path. Use this to validate a template before saving it.

Partially update a correspondent. Only the fields you pass are changed; omitted fields keep their current value.

Rename a custom field or adjust its extra_data (e.g. add select options). Changing data_type is not supported by Paperless.

Change metadata on a single document. Only the fields you pass are modified. Pass numeric IDs for correspondent, document_type and storage_path — resolve names via get_metadata_overview first. Setting tags replaces the whole tag list; to add or remove individual tags across documents use bulk_edit_documents.

Partially update a document type. Only the fields you pass are changed; omitted fields keep their current value.

Change a saved view's name, sorting, visibility or filter rules.

Partially update a storage path. Only the fields you pass are changed; omitted fields keep their current value.

Partially update a tag. Only the fields you pass are changed; omitted fields keep their current value.

Update a workflow. Passing triggers or actions replaces the existing list wholesale — fetch the current definition with get_workflow, modify it, and send the complete list back. To simply switch a rule off, pass enabled:false and nothing else.

Hand a file to Paperless for consumption. Provide either path (a file on the machine running this server — the cheap option) or content_base64 (works for remote deployments but costs context proportional to the file size; avoid for anything over a few hundred kilobytes). Consumption is asynchronous: the returned task ID can be polled with get_task.