Repository navigation
Releases
v3.2.1
Safer tag edits and fewer calls when an agent files or reads documents. Tested against Paperless-ngx 3.2.1, the latest Paperless release. No breaking changes: every new parameter is optional.
Upgrading: start a new chat after updating. A chat that was already open can keep using the old tool definitions and won't see the new parameters.
Fixed
update_documentcould silently drop tags.tagsreplaces the document's whole tag list, and the tool didn't say so, so adding one tag from an incomplete list removed the others. The newadd_tags/remove_tagschange single tags and leave the rest alone; passingtagstogether with either is refused. Every tag change, including a fulltagsreplace, now returnstag_changes: { added, removed }, so a dropped tag shows up in the result.- An empty
search_documentsresult looked final. Paperless updates its full-text index in the background, so the index can lag behind or miss documents and "No documents found" wasn't always true. The empty result now says so and points tolist_documentssearch, which matches straight from the database.
Added
get_filing_options: every tag, correspondent, document type, storage path and custom field in one call (id and name, sorted by name; tags also showis_inbox_tag, custom fields theirdata_type). One call instead of five before filing a document, and it still works when a client hasn't loaded one of thelist_*tools.list_documentsids(Paperlessid__in): read several known documents in one call.fieldsonlist_documentsandget_document: return only the fields you need, e.g.["title", "tags"].idis always included, and correspondent, type, tag and custom-field names are still resolved.get_document_contentmax_chars/offset: read a long document in slices. The result then addsoffset,total_charsandtruncated; without either parameter the output is unchanged.search_documentsmode:query(the default; advanced syntax with AND/OR/NOT, quoted phrases,field:valueand wildcards),text(plain words, no syntax) ortitle(titles only).
Changed
- Workflow trigger filters now say which trigger types use them.
sources,filter_pathandfilter_mailruleapply only to consumption-started triggers (type 1). The tag, correspondent, document-type and storage-path filters,filter_custom_field_queryand content matching apply only to added, updated and scheduled triggers (types 2–4).filter_filenameapplies to all four. list_documentssearchnow explains what it matches: a case-insensitive substring match on title, correspondent name and content, read straight from the database, where every word must appear. Usesearch_documentsfor ranked full-text search.update_documenttitlenotes that Paperless derives the stored file name from the title and replaces characters not allowed in file names (such as/), soarchived_file_namecan differ from the title.- The server instructions point to
get_filing_optionsfor looking up everything a document can be filed under.
Full Changelog: v3.2.0...v3.2.1
v3.2.0
Aligns the tool surface with Paperless-ngx 3.2 and drops support for older Paperless versions.
Fixed
- Workflow actions could not express 4 of the 8 action types.
create_workflow_action/update_workflow_actionnow accept types 5 (password removal), 6 (move to trash), 7 (remote OCR) and 8 (apply AI suggestions) with their fields (passwords,ai_suggestion_fields,ai_create_missing,ai_overwrite_existing), plusassign_custom_fields_valuesand the per-item removal lists (remove_correspondents,remove_document_types,remove_storage_paths,remove_owners,remove_view_*,remove_change_*). - Workflow triggers used the legacy singular filters. Triggers now take the any/all/not forms the web UI writes (
filter_has_all_tags,filter_has_not_tags,filter_has_any_*/filter_has_not_*for correspondents, document types and storage paths) andfilter_custom_field_query.matching_algorithmis limited to 0–5, the range triggers support. list_documentsdocumented acustom_field_querysyntax Paperless rejects. The description now gives the JSON expression syntax (["Amount", "gte", 100],["AND", […]]).- Paperless error details were dropped. Validation errors (
{"non_field_errors": ["password not specified"]}) and plain-text errors ("AI is required for this feature") now appear in the tool error instead of a bare "status code 400" — for every JSON API call and for version uploads;post_documentuploads still report only the status. HTML error pages are still reduced to the status line. - A slow Paperless response could leave a tool call hanging until the MCP client gave up. Every JSON API call now has a 90-second overall deadline and fails with a message naming the endpoint. Downloads are exempt.
list_taskslimitabove 25 returned only 25 tasks; it is now passed to the server as the page size.list_trashreturned the full text of every trashed document, which could overflow the model's context. Content is now left out, as inlist_documents.
Added
- Workflows:
list_workflows,get_workflow,create_workflow,update_workflow,delete_workflow. A workflow, with its nested triggers and actions, is what Paperless actually runs; standalone triggers and actions do nothing on their own (and Paperless deletes unattached ones whenever a workflow is updated).get_workflowoutput can be edited and sent straight back toupdate_workflow;create_workflowignores nested ids, so copying a workflow never takes over the original's triggers. Webhook actions gainas_jsonandinclude_document. - Document versions:
upload_document_version(reports the document'sdocument_idand the newversion_id),update_document_version,delete_document_version,merge_documents_as_versions. edit_documents_bulk: methodremove_password(withupdate_document: truethe unlocked file becomes a new version),remote_ocrfor methodreprocess, andall+filters(+excluded_documents) to select every matching document, e.g. to reassign all documents of a duplicate correspondent in one call. Filter keys Paperless would silently ignore (which would select every document) are refused, invalid values are caught by a preview query, and the result reportsmatched_documents.list_documents:has_duplicatesfilter.- Mail:
list/get/create/update/delete_mail_account,test_mail_account(pass a saved account'sidto test it with its stored password),process_mail_account,list/get/create/update/delete_mail_rule. - Share link bundles:
list/get/create/rebuild/delete_share_link_bundle(s). - System:
get_system_status(includes the Paperless version),get_document_ai_suggestions,list_active_tasks,get_task_status_counts,get_task_summary.list_tasksacceptstask_type: apply_ai_suggestions. get_documentnow explains which fields follow the latest version (content, metadata) and which describe the root (page_count, file names).- Distribution: the release workflow now also publishes a Docker image to
ghcr.io/cubinet-code/paperless-ngx-mcp(linux/amd64 and linux/arm64; stdio by default,--httpfor Streamable HTTP), attaches a Claude Desktop extension (paperless-ngx-mcp.mcpb) to each GitHub Release, and lists the server in the official MCP Registry asio.github.cubinet-code/paperless-ngx-mcp.
Changed (BREAKING)
- Paperless-ngx 2.x is no longer supported. The 2.x compatibility code (task status casing fallback, flat
/tasks/arrays,related_document/result) is gone. Stay on3.1.1for Paperless 2.x. list_tasksdropped the 2.x-only filterstask_nameandtype. Usetask_typeandtrigger_source.update_share_linkwas removed. Paperless has never allowed editing a share link (the endpoint only supports GET and DELETE), so every call failed with HTTP 405. Delete and recreate the link instead.- Workflow triggers no longer accept
filter_has_correspondent/filter_has_document_type. Usefilter_has_any_correspondents/filter_has_any_document_types. edit_documents_bulkdocumentsis optional whenall: true+filtersis given. Exactly one of the two selection forms is required.
Security
- Workflow PDF passwords no longer reach the model in clear text.
list_workflows,get_workflow,list_workflow_actions,get_workflow_actionand the create/update results show the passwords of password-removal actions as**********. Sending the masked list back toupdate_workflow/update_workflow_actionkeeps the stored passwords; creating an action from masked passwords is refused. @modelcontextprotocol/sdk1.30.0→1.30.1(caps JSON-RPC batches at 100 messages) and in-range transitive bumps fromnpm audit fix:fast-uri3.1.5→3.1.8(high: host confusion via skipped IDN canonicalization),hono4.13.1→4.13.8andqs6.15.3→6.16.0(moderate).npm auditis clean.
Full Changelog: v3.1.1...v3.2.0
v3.1.1
Security
- Cleared 42 Dependabot alerts (9 high, 29 moderate, 4 low) by bumping transitive and direct dependencies within their existing semver ranges — no
--force, no breaking changes:@modelcontextprotocol/sdk1.29.0→1.30.0, pulling in patchedhono(4.12.17→4.13.1) and@hono/node-server(1.19.14→2.1.0). Most of thehonoadvisories (JSX SSR, CORS, cookie/JWT middleware, Lambda adapters) are in code paths this server never exercises — we use Express for our own HTTP transport — but the patched versions clear them regardless.express-rate-limit'sip-address10.2.0→10.5.0(SSRF/trust-boundary bypasses via octal/CIDR/IPv6-mapped address confusion).axios1.16.0→1.19.0(prototype pollution,maxBodyLengthbypasses, proxy handling).form-data4.0.5→4.0.6(CRLF injection via unescaped multipart field names).ajv'sfast-uri3.1.0→3.1.5(host confusion / path traversal in URI parsing).express'sbody-parser2.2.2→2.3.0andqs6.15.1→6.15.3.- Dev-only:
tsx4.21.0→4.23.12, pulling in patchedesbuild(0.27.7→0.28.2; arbitrary file read inesbuild's dev server on Windows — not shipped in the published package). npm auditis now clean (0 vulnerabilities). Verified:tsc --noEmit, 75/75 unit tests, 15/15 e2e againstpaperless-ngx:2.20.15, including the full HTTP session/SSE suite against the new SDK version.
Full Changelog: v3.1.0...v3.1.1
v3.1.0
Fixed
- The HTTP transport could only serve one client at a time.
--httpmode shared a singleMcpServeracross every connection, but the MCP SDK binds one server to exactly one transport — so a second concurrent client failed withAlready connected to a transport(HTTP 500). Each session now gets its own server instance. The same latent fault affected the legacy/sseendpoint, where a second connection could displace the first; it is fixed there too. - HTTP sessions are now durable.
POST /mcpissues anMcp-Session-Idoninitializeand reuses it on later requests, instead of treating every request as a fresh stateless exchange. Clients that expect session continuity (per the Streamable HTTP spec) no longer seeSession terminated. GET /mcpandDELETE /mcpnow work instead of always returning 405.GETopens the server-to-client stream for a session;DELETEterminates it.
Added
- Session limits, so an unauthenticated port cannot exhaust memory. Each session pins a full server (~3.5 MB), so sessions are capped (default 50,
--maxSessions/PAPERLESS_MAX_SESSIONS) and idle sessions are evicted (default 30 minutes,--sessionIdleMinutes/PAPERLESS_SESSION_IDLE_MINUTES). Past the cap,initializeis refused with HTTP 503 rather than allocating. A client that is actively connected — including one holding aGET /mcpstream open — is never evicted, however long it sits idle./sseconnections draw from the same cap, so it is refused with 503 too once the budget is spent — it was previously unbounded even after/mcpwas capped. SIGTERM/SIGINTnow tear down live sessions before exit.
Changed (BREAKING)
--httpmode is stateful. Clients that never callinitialize, or that call it and then ignore the returnedMcp-Session-Id, previously worked against the stateless server and now receive HTTP 400. Sendinitializefirst and echo the session id back on subsequent requests. Only--httpis affected — stdio behaviour is unchanged.GET/DELETEon/mcpwithout a session id return 400 (was 405); with an unknown or expired session id they return 404.- The HTTP startup log line dropped the word
Stateless.
Full Changelog: v3.0.0...v3.1.0
v3.0.0
Adds support for Paperless-ngx 3.x, which reworked the task API. Paperless 2.x remains supported — the tools detect and adapt to either server.
The version jumps from 0.1.6 to 3.0.0 so the major tracks the Paperless-ngx major it targets. There are no 1.x or 2.x releases of this package.
Fixed
list_tasksfailed outright against Paperless 3.x. 3.0 paginates/api/tasks/({count, next, previous, results}); 2.x returned a bare array. The tool sliced the response directly and died withresponse.slice is not a function. Both shapes are now accepted and the tool still returns a plain array.post_documentwithpoll: truenever completed against Paperless 3.x. Two independent causes, both silent — the upload succeeded but the tool always reported a timeout with nodocument_id:- the consumer poll read
/api/tasks/?task_id=…as an array, so it never found its task on 3.x; - terminal-state detection compared against uppercase
SUCCESS/FAILURE/REVOKED, but 3.x reports lowercasesuccess/failure/revoked. Status comparison is now case-insensitive.
- the consumer poll read
post_documentreturned nodocument_idon Paperless 3.x even when the consumer succeeded: 3.x replaced the task'srelated_documentwith arelated_document_idsarray. Both are now read.
Added
list_tasksgained the Paperless 3.x filterstask_typeandtrigger_source. The 2.xtask_nameandtypefilters are kept for older servers. Each server silently ignores the filters it does not know, so the correct pair applies automatically; the tool descriptions say which version each belongs to.task_typecovers the task kinds 3.x added:mail_fetch,llm_index,empty_trash,check_workflows,bulk_update,reprocess_document,build_share_link,bulk_delete. Note that 2.x'scheck_sanityissanity_checkin 3.x.
Changed (BREAKING)
list_tasksstatusvalues are now lowercase (success, notSUCCESS), matching the 3.x vocabulary. Paperless 2.x requires uppercase and rejects lowercase with a 400, so the tool retries with the other casing and remembers which the server accepted — callers pass lowercase either way.list_tasksno longer acceptsstatus: "RETRY"or"RECEIVED". Paperless 3.x removed both from the task status enum.post_documentreports the server's own status casing in its result (successon 3.x,SUCCESSon 2.x) rather than always uppercasing it.
Full Changelog: v0.1.6...v3.0.0
v0.1.6
Added
post_documentcan now wait for the consumer. New optionalpollflag: whentrue, the tool waits for the Paperless consumer task to finish and returns the final result in a single call — the newdocument_idon success, or the consumer error (e.g.InputFileError) on failure — instead of just a task UUID you have to chase vialist_tasks. New optionalpoll_timeout_seconds(default 30, max 300) caps the wait and returns the in-progress status on timeout; raise it for large scans where OCR is slow. Default behaviour is unchanged — withoutpoll, the tool still returns the task UUID immediately.
Fixed
post_documentno longer misleads callers about thefilepath option on remote deployments. Thefileparameter description now makes clear that base64 content is the universal method (the bytes travel over the wire) and that the absolute-path option only works when the MCP server runs on the same machine as the file (local/stdio deployments). When a path can't be read (e.g. a remote server can't see the caller's filesystem), the bareENOENTis replaced with a message that explains why and tells the caller to pass base64 instead — so an AI client can self-correct instead of dead-ending.
Full Changelog: v0.1.5...v0.1.6
v0.1.5
Security
- Bumped transitive dependency
ip-addressto 10.2.0 (viaexpress-rate-limit8.5.1) to clear GHSA-v2v4-37r5-5v8g — XSS inAddress6HTML-emitting methods. The vulnerable methods were not reachable from this codebase, so no functional change;npm auditis now clean.
Changed
- Release workflow now extracts release notes from the matching
## [<version>]section ofCHANGELOG.mdand fails the release if that section is missing. Previous setup derived notes from PR titles, leaving release pages empty when work landed directly onmain(as on v0.1.4).
Full Changelog: v0.1.4...v0.1.5
v0.1.4
Highlights: This release fixes two long-standing bugs in
edit_documents_bulk(formerlybulk_edit_documents) wheremodify_custom_fieldsalways returned HTTP 400 andset_permissionsalways returned HTTP 500. It also renames every bulk operation to a verb-first naming scheme so that wildcard permission allowlists group cleanly by operation, drops a staleAccept: …version=5header pin, and adds the upstreamedit_pdfbulk method. New schema-driven e2e tests now run against a live Paperless 2.20.15 container and will fail when upstream changes its API.
Fixed
edit_documents_bulkmethodmodify_custom_fieldswas always rejected by Paperless with HTTP 400"add_custom_fields not specified". The wire payload now usesadd_custom_fields({field_id: value}dict, per upstreamBulkEditSerializer) andremove_custom_fields(list of ids), and includes both keys whenever the method ismodify_custom_fields. Previously the tool emittedassign_custom_fields/assign_custom_fields_values, neither of which the upstream serializer recognises. Tool input shape is unchanged —add_custom_fields: [{field, value}, …]still works and is now translated to the dict form on the wire.edit_documents_bulkmethodset_permissionsfailed with HTTP 500.set_permissions,owner, andmergeare now top-level parameters on the tool (siblings ofdocumentsandmethod), matching the upstream_validate_parameters_set_permissionsshape. The previous nestedpermissions: {set_permissions, owner, merge}wrapper has been removed.Accept: application/json; version=5header pin removed. The server defaults to its current API version (currently 9), so document, tag, and custom-field responses now include fields likecreatedanduserthat v5 hid.
Added
edit_documents_bulkmethodedit_pdfis now exposed (added upstream in Paperless-NGX 2.16). Acceptsoperations: [{page, rotate?, doc?}], plus optionalupdate_documentandinclude_metadataflags.- Schema-driven e2e tests that fetch the live
/api/schema/from a running Paperless container:tests/e2e/schema_coverage.e2e.test.ts— fails when upstream adds, removes, or renames an endpoint, forcing a triage decision (wrap the new endpoint, or document the skip). Also verifies ouredit_documents_bulkmethod enum stays in sync with upstream'sMethodEnum.tests/e2e/bulk_edit.e2e.test.ts— round-trips realmodify_custom_fieldsandset_permissionspayloads against a real container, asserting observable side effects (custom-field value applied, owner changed, etc.).
- E2e harness now applies each tool's Zod schema before invoking the body, so e2e tests exercise the full input pipeline (schema validation + body + API), the same way the real MCP SDK does.
Changed
- E2e Paperless container bumped from
2.13to2.20.15(latest stable). Required foredit_pdfand current OpenAPI schema coverage.
Changed (BREAKING)
If you upgrade and your AI agent or hand-written client makes bulk operations, read this section.
1. Bulk-operation tool names are now verb-first
Tool names changed so that wildcard-based permission allowlists group cleanly by operation. Migrate any client config (Claude Code permissions, Codex allowlists, Cursor rules, hand-written allowlists) that references the old names:
| Old name | New name |
|---|---|
bulk_download |
download_documents_bulk |
bulk_edit_documents |
edit_documents_bulk |
bulk_edit_tags |
edit_tags_bulk |
bulk_edit_correspondents |
edit_correspondents_bulk |
bulk_edit_document_types |
edit_document_types_bulk |
bulk_edit_custom_fields |
edit_custom_fields_bulk |
Behaviour and parameters are unchanged — only the names. After upgrading, download_* covers single + bulk downloads and edit_*_bulk covers every bulk-edit family. See the README's "Tool naming convention" table for the recommended allowlist patterns.
2. edit_documents_bulk set_permissions parameter shape
If you build set_permissions payloads by hand (vs. letting the LLM produce them), the wrapping permissions: object is gone and set_permissions / owner / merge are siblings at the top level.
edit_documents_bulk({
documents: [1, 2],
method: "set_permissions",
- permissions: {
- set_permissions: { view: { users: [1] }, change: { users: [2] } },
- owner: 1,
- merge: false,
- },
+ set_permissions: { view: { users: [1] }, change: { users: [2] } },
+ owner: 1,
+ merge: false,
})3. edit_documents_bulk modify_custom_fields
The tool's input shape is unchanged (add_custom_fields: [{field, value}, …], remove_custom_fields: [id, …]). What changed is the wire format: it used to silently fail with HTTP 400 on every call, and now succeeds. Anyone who had this method "working" against their server is on a custom fork.
Full Changelog: v0.1.3...v0.1.4
v0.1.3
v0.1.3
Internal refactor for code reuse, code quality, and efficiency, plus
a new triage_inbox prompt and a small set of efficiency wins. No
breaking changes — all existing tools accept the same arguments and
return the same response shapes as v0.1.2.
New
- triage_inbox prompt: an MCP prompt that walks an LLM agent
through reviewing the Paperless inbox, proposing
correspondent / document type / tag metadata that prefers existing
items, and gating execution on explicit user confirmation before
any writes.
Changed
- Heavy deduplication across tool files: shared zod field schemas
(pagination, name filters, matching algorithm, permissions),
shared helpers for confirmation guards / "deleted" responses /
Content-Disposition parsing, and aregisterBulkEditToolfactory
that collapses three near-identical bulk-edit registrations. list_documents,search_autocomplete, andlist_tasksnow
build query strings via the shared helper instead of hand-rolling
URLSearchParams.PaperlessAPI.request<T>defaults tounknowninstead ofany;
bulkEditObjectsgained proper type annotations;postDocument
metadata is typed; unreachable axios status checks removed.documentEnhancer.tsdeduplicated against the shared
CustomFieldInstancetype, dead null-input branch removed,
two-pass map collapsed to one.post_documentswitched from synchronousfs.readFileSyncto
fs.promises.readFileand tightened base64 validation.- Section-divider and dead inline comments removed across the
codebase; ~50 deadif (!api) throwguards deleted from tool
handlers.
Performance
fetchAllPagesparallelizes pages 2..N when the result set
exceeds one page (Math.ceil(count / 100)pages issued via
Promise.all). Sequential fallback preserved for small or
count-less responses.convertDocsWithNamesnow skips fetching correspondents /
document types / tags / custom fields when no document in the
response references that entity type. Aget_documenton a
thin record can drop from 4 metadata calls to 0.
Internal
- New shared helpers in
src/tools/utils:schemas.ts,
responses.ts,bulkEdit.ts,listFilter.ts. - Net diff vs v0.1.2: ~800 lines removed, ~350 added.