@retiform/paperless-mcp 0.0.0-stage → 2.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +1005 -2
  3. package/build/api/PaperlessAPI.d.ts +63 -0
  4. package/build/api/PaperlessAPI.js +405 -0
  5. package/build/api/documentEnhancer.d.ts +24 -0
  6. package/build/api/documentEnhancer.js +111 -0
  7. package/build/api/documentEnhancer.test.d.ts +1 -0
  8. package/build/api/documentEnhancer.test.js +80 -0
  9. package/build/api/types.d.ts +203 -0
  10. package/build/api/types.js +15 -0
  11. package/build/api/utils.d.ts +16 -0
  12. package/build/api/utils.js +29 -0
  13. package/build/index.d.ts +2 -0
  14. package/build/index.js +189 -0
  15. package/build/resources/documents.d.ts +7 -0
  16. package/build/resources/documents.js +119 -0
  17. package/build/resources/documents.test.d.ts +1 -0
  18. package/build/resources/documents.test.js +124 -0
  19. package/build/server.d.ts +24 -0
  20. package/build/server.js +70 -0
  21. package/build/server.test.d.ts +1 -0
  22. package/build/server.test.js +54 -0
  23. package/build/test/mocks/paperlessApi.d.ts +4 -0
  24. package/build/test/mocks/paperlessApi.js +33 -0
  25. package/build/tools/boundedContent.test.d.ts +1 -0
  26. package/build/tools/boundedContent.test.js +544 -0
  27. package/build/tools/correspondents.d.ts +3 -0
  28. package/build/tools/correspondents.js +149 -0
  29. package/build/tools/customFields.d.ts +3 -0
  30. package/build/tools/customFields.js +142 -0
  31. package/build/tools/documentTypes.d.ts +3 -0
  32. package/build/tools/documentTypes.js +143 -0
  33. package/build/tools/documents.d.ts +134 -0
  34. package/build/tools/documents.js +814 -0
  35. package/build/tools/documents.test.d.ts +1 -0
  36. package/build/tools/documents.test.js +658 -0
  37. package/build/tools/mail.d.ts +3 -0
  38. package/build/tools/mail.js +187 -0
  39. package/build/tools/mail.test.d.ts +1 -0
  40. package/build/tools/mail.test.js +212 -0
  41. package/build/tools/notes.d.ts +3 -0
  42. package/build/tools/notes.js +55 -0
  43. package/build/tools/notes.test.d.ts +1 -0
  44. package/build/tools/notes.test.js +177 -0
  45. package/build/tools/schemaCompat.test.d.ts +1 -0
  46. package/build/tools/schemaCompat.test.js +59 -0
  47. package/build/tools/tags.d.ts +3 -0
  48. package/build/tools/tags.js +143 -0
  49. package/build/tools/utils/descriptions.d.ts +1 -0
  50. package/build/tools/utils/descriptions.js +4 -0
  51. package/build/tools/utils/documentQuery.d.ts +71 -0
  52. package/build/tools/utils/documentQuery.js +270 -0
  53. package/build/tools/utils/empty.d.ts +2 -0
  54. package/build/tools/utils/empty.js +7 -0
  55. package/build/tools/utils/matchingAlgorithm.d.ts +2 -0
  56. package/build/tools/utils/matchingAlgorithm.js +15 -0
  57. package/build/tools/utils/middlewares.d.ts +3 -0
  58. package/build/tools/utils/middlewares.js +31 -0
  59. package/build/tools/utils/monetary.d.ts +5 -0
  60. package/build/tools/utils/monetary.js +34 -0
  61. package/build/tools/utils/monetary.test.d.ts +1 -0
  62. package/build/tools/utils/monetary.test.js +25 -0
  63. package/build/tools/utils/queryString.d.ts +1 -0
  64. package/build/tools/utils/queryString.js +12 -0
  65. package/build/tools/utils/resourceUri.d.ts +29 -0
  66. package/build/tools/utils/resourceUri.js +37 -0
  67. package/build/tools/utils/resourceUri.test.d.ts +1 -0
  68. package/build/tools/utils/resourceUri.test.js +50 -0
  69. package/build/tools/utils/selectFields.d.ts +13 -0
  70. package/build/tools/utils/selectFields.js +91 -0
  71. package/build/tools/utils/selectFields.test.d.ts +1 -0
  72. package/build/tools/utils/selectFields.test.js +164 -0
  73. package/package.json +59 -4
  74. package/paperless-mcp.dxt +0 -0
package/README.md CHANGED
@@ -1,3 +1,1006 @@
1
- # Temporary Holding Version
1
+ <!-- [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/nloui-paperless-mcp-badge.png)](https://mseep.ai/app/nloui-paperless-mcp) -->
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # Paperless-NGX MCP Server
4
+
5
+ ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/retiform-labs/paperless-mcp?utm_source=oss&utm_medium=github&utm_campaign=retiform-labs%2Fpaperless-mcp&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
6
+
7
+ 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.
8
+
9
+ ## About this fork
10
+
11
+ This is a fork of [baruchiro/paperless-mcp](https://github.com/baruchiro/paperless-mcp)
12
+ (ISC license, (c) Baruch Odem), maintained by **Retiform Labs** and published as
13
+ **`@retiform/paperless-mcp`**. Fork point: tag `upstream-v2.2.1`.
14
+
15
+ Upstream returns whole documents. That is fine for a human clicking through a UI
16
+ and crippling for an agent: a single `get_document_content` call on a
17
+ several-hundred-page PDF can consume an entire context window, and there is no
18
+ way to ask for a slice. This fork adds bounded reads:
19
+
20
+ - **Ranged `get_document_content`** -- `offset` + `max_chars` windows, with honest
21
+ `content_length` / `truncated` / `has_more` metadata.
22
+ - **`search_passages`** -- full-text hits returned as bounded passages around the
23
+ actual match, with score and offset, so an agent can locate and then page into
24
+ the exact region it needs.
25
+ - **An inline budget** -- `PAPERLESS_MCP_MAX_INLINE_CHARS` makes an oversized
26
+ request fail loudly instead of silently flooding the caller.
27
+ - **`content_length`** on list/query/get results, so a client can size a read
28
+ before making it.
29
+ - **Query resilience** -- an apostrophe in a search query is retried sanitized
30
+ instead of returning a hard 400.
31
+
32
+ We also fix the build so it is idempotent (`tsc` no longer consumes its own
33
+ `.d.ts` output on a rebuild). Upstream was unable to take this work, and agentic
34
+ clients need it now, so it is published here. The delta from `upstream-v2.2.1`
35
+ is small and self-contained if upstream ever wants it.
36
+
37
+ ## Quick Start
38
+
39
+ [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=paperless&config=eyJjb21tYW5kIjoibnB4IC15IEByZXRpZm9ybS9wYXBlcmxlc3MtbWNwQGxhdGVzdCIsImVudiI6eyJQQVBFUkxFU1NfVVJMIjoiaHR0cDovL3lvdXItcGFwZXJsZXNzLWluc3RhbmNlOjgwMDAiLCJQQVBFUkxFU1NfQVBJX0tFWSI6InlvdXItYXBpLXRva2VuIn19)
40
+
41
+ ### Installation
42
+
43
+ Add these to your MCP config file:
44
+
45
+ // STDIO mode (recommended for local or CLI use)
46
+ ```json
47
+ "paperless": {
48
+ "command": "npx",
49
+ "args": [
50
+ "-y",
51
+ "@retiform/paperless-mcp@latest",
52
+ ],
53
+ "env": {
54
+ "PAPERLESS_URL": "http://your-paperless-instance:8000",
55
+ "PAPERLESS_API_KEY": "your-api-token",
56
+ "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
57
+ }
58
+ }
59
+ ```
60
+
61
+ // HTTP mode (recommended for Docker or remote use)
62
+ ```json
63
+ "paperless": {
64
+ "command": "docker",
65
+ "args": [
66
+ "run",
67
+ "-i",
68
+ "--rm",
69
+ "ghcr.io/retiform-labs/paperless-mcp:latest",
70
+ ],
71
+ "env": {
72
+ "PAPERLESS_URL": "http://your-paperless-instance:8000",
73
+ "PAPERLESS_API_KEY": "your-api-token",
74
+ "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
75
+ }
76
+ }
77
+ ```
78
+
79
+ 3. Get your API token:
80
+ 1. Log into your Paperless-NGX instance
81
+ 2. Click your username in the top right
82
+ 3. Select "My Profile"
83
+ 4. Click the circular arrow button to generate a new token
84
+
85
+ 4. Replace the placeholders in your MCP config:
86
+ - `http://your-paperless-instance:8000` with your Paperless-NGX URL
87
+ - `your-api-token` with the token you just generated
88
+ - `https://your-public-domain.com` with your public Paperless-NGX URL (optional, falls back to PAPERLESS_URL)
89
+
90
+ ### Environment Variables
91
+
92
+ | Variable | Required | Default | Description |
93
+ |---|---|---|---|
94
+ | `PAPERLESS_URL` | Yes | — | Base URL of your Paperless-NGX instance |
95
+ | `PAPERLESS_API_KEY` | Yes | — | API token from your Paperless-NGX profile |
96
+ | `PAPERLESS_PUBLIC_URL` | No | `PAPERLESS_URL` | Public-facing URL for document links |
97
+ | `PAPERLESS_API_VERSION` | No | `9` | Paperless-ngx REST API version. `9` works on Paperless-ngx v2.x (recent) and v3.x. Paperless-ngx v3.0.0 dropped support for versions below `9`, so older defaults now return HTTP 406. If you see HTTP 406 errors, set this to a version your server supports. |
98
+ | `PAPERLESS_MCP_UPLOAD_PATHS` | No | — | Colon-separated list of allowed directories for `file_path` uploads. **Recommended for security.** Example: `/var/uploads:/tmp/scans` |
99
+ | `PAPERLESS_MCP_MAX_INLINE_CHARS` | No | `50000` | Hard cap on characters a single tool response may inline. Requests above the budget fail with the document size and a hint toward bounded reads instead of silently truncating or flooding context. |
100
+
101
+ That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.
102
+
103
+ ### Example Usage
104
+
105
+ Here are some things you can ask Claude to do:
106
+
107
+ - "Show me all documents tagged as 'Invoice'"
108
+ - "Search for documents containing 'tax return'"
109
+ - "Create a new tag called 'Receipts' with color #FF0000"
110
+ - "Download document #123"
111
+ - "List all correspondents"
112
+ - "Create a new document type called 'Bank Statement'"
113
+
114
+ ## Available Tools
115
+
116
+ ### Document Operations
117
+
118
+ #### list_documents
119
+ Get a paginated list of documents with simple filters. Use this for straightforward listing tasks. For full-text queries, structured custom field filtering, or advanced Paperless filters, use `query_documents`.
120
+
121
+ Parameters:
122
+ - page (optional): Page number
123
+ - page_size (optional): Number of documents per page
124
+ - search (optional): Simple Paperless search term
125
+ - correspondent (optional): Correspondent ID
126
+ - document_type (optional): Document type ID
127
+ - tag (optional): Tag ID
128
+ - storage_path (optional): Storage path ID
129
+ - created__date__gte (optional): Created date on or after YYYY-MM-DD
130
+ - created__date__lte (optional): Created date on or before YYYY-MM-DD
131
+ - ordering (optional): Paperless ordering field
132
+ - archive_serial_number (optional): Archive serial number
133
+ - archive_serial_number__isnull (optional): Whether the archive serial number is empty
134
+ - custom_field_query (optional): Raw JSON-encoded Paperless custom field query string
135
+ - custom_fields__icontains (optional): Case-insensitive substring match across custom field values
136
+
137
+ ```typescript
138
+ list_documents({
139
+ page: 1,
140
+ page_size: 25
141
+ })
142
+ ```
143
+
144
+ #### query_documents
145
+ Canonical document query tool. Supports full-text querying, simple Paperless search, custom field filters, and documented `/api/documents/` Paperless query parameters.
146
+
147
+ Parameters:
148
+ - page (optional): Page number
149
+ - page_size (optional): Number of documents per page
150
+ - ordering (optional): Paperless ordering field
151
+ - query (optional): Full-text query string
152
+ - search (optional): Simple Paperless search term
153
+ - more_like_id (optional): Find documents similar to this document ID
154
+ - correspondent (optional): Correspondent ID
155
+ - document_type (optional): Document type ID
156
+ - tag (optional): Tag ID
157
+ - storage_path (optional): Storage path ID
158
+ - created__date__gte (optional): Created date on or after YYYY-MM-DD
159
+ - created__date__lte (optional): Created date on or before YYYY-MM-DD
160
+ - custom_field_query (optional): Structured Paperless custom field query using `[field_name_or_id, operator, value]` leaves or `["AND" | "OR", [clause1, clause2]]` groups
161
+ - paperless_filters (optional): Additional documented `/api/documents/` Paperless query parameters, passed as key/value pairs
162
+
163
+ ```typescript
164
+ // Full-text query
165
+ query_documents({
166
+ query: "invoice 2024"
167
+ })
168
+
169
+ // Simple search term
170
+ query_documents({
171
+ search: "acme"
172
+ })
173
+
174
+ // Custom field exact match
175
+ query_documents({
176
+ custom_field_query: ["Invoice Number", "exact", "12345"]
177
+ })
178
+
179
+ // Custom field empty
180
+ query_documents({
181
+ custom_field_query: ["OR", [
182
+ ["Invoice Number", "isnull", true],
183
+ ["Invoice Number", "exact", ""]
184
+ ]]
185
+ })
186
+
187
+ // Custom field missing
188
+ query_documents({
189
+ custom_field_query: ["Invoice Number", "exists", false]
190
+ })
191
+
192
+ // Combined filters
193
+ query_documents({
194
+ query: "invoice",
195
+ tag: 5,
196
+ created__date__gte: "2024-01-01",
197
+ custom_field_query: ["Invoice Number", "exists", true]
198
+ })
199
+
200
+ // One documented Paperless filter that is not a first-class argument
201
+ query_documents({
202
+ paperless_filters: {
203
+ id__in: [101, 202, 303]
204
+ }
205
+ })
206
+ ```
207
+
208
+ #### get_document
209
+ Get a specific document by ID.
210
+
211
+ Parameters:
212
+ - id: Document ID
213
+
214
+ ```typescript
215
+ get_document({
216
+ id: 123
217
+ })
218
+ ```
219
+
220
+ #### search_documents
221
+ Deprecated compatibility wrapper for full-text search. Prefer `query_documents({ query: ... })` for new integrations.
222
+
223
+ Parameters:
224
+ - query: Search query string
225
+
226
+ ```typescript
227
+ search_documents({
228
+ query: "invoice 2024"
229
+ })
230
+ ```
231
+
232
+ #### get_document_content
233
+ Get the text content of a document by ID **in bounded windows**. Returns at most `max_chars` characters (default 8000) starting at `offset`, plus pagination metadata so callers can page through long documents without flooding context.
234
+
235
+ Parameters:
236
+ - id: Document ID
237
+ - offset (optional): Character offset to start reading from (default 0)
238
+ - max_chars (optional): Maximum characters to return (default 8000)
239
+
240
+ ```typescript
241
+ get_document_content({ id: 123 })
242
+ // → { content: "<first 8000 chars>", offset: 0, content_length: 726573, returned_chars: 8000, truncated: true, has_more: true }
243
+
244
+ get_document_content({ id: 123, offset: 8000, max_chars: 8000 })
245
+ // → next window
246
+ ```
247
+
248
+ Requests above the inline budget (`PAPERLESS_MCP_MAX_INLINE_CHARS`, default 50000) fail with the document size and a hint toward offset reads or the `download_document` resource — never a silent slice, never an unbounded return. The response always carries `content_length`, `truncated`, and `has_more` so callers can page deterministically.
249
+
250
+ #### search_passages
251
+ Search documents full-text and return **bounded text passages around each hit** instead of whole documents. Each window is anchored on the server's own highlighted phrase (falling back to the first verbatim term occurrence, then the document head), so the returned passage contains the actual hit even when the search index stemmed a word variant that does not appear verbatim in the stored text. Returns the document id, title, score, offset, `content_length`, and the highlighted snippet.
252
+
253
+ Queries that the server rejects with an opaque HTTP 400 (django-watson rejects some syntactically valid queries, notably those containing apostrophes) are retried once with a defensively rewritten query — apostrophes and stray quotes removed; structured filter values are never rewritten. Responses from a rewritten retry carry `query_sanitized: true`. Persistent failures throw a structured error naming every attempted query.
254
+
255
+ Parameters:
256
+ - query: Search query string (same syntax as `query_documents`)
257
+ - window (optional): Characters per passage (default 800, range 200–4000)
258
+ - max_passages (optional): Maximum passages to return (default 5, cap 20)
259
+
260
+ ```typescript
261
+ search_passages({ query: "invoice 2024" })
262
+ // → { query: "invoice 2024", total_hits: 3, passages: [{ id, title, score, highlights, passage, offset, content_length }, ...] }
263
+
264
+ search_passages({ query: "God's will" })
265
+ // → { ..., query_sanitized: true, ... } // apostrophe stripped on retry after a 400
266
+ ```
267
+
268
+ Use this to locate and skim evidence across many documents in a single call; page further into a hit with `get_document_content` offsets. Standard `query_documents` filters (`correspondent`, `tag`, `document_type`, `storage_path`, date ranges, `paperless_filters`) are accepted and behave identically. Note: `total_hits` reflects the server's OR-expanded match count and may exceed the number of top-ranked passages returned.
269
+
270
+ #### download_document
271
+ Download a document file by ID.
272
+
273
+ Parameters:
274
+ - id: Document ID
275
+ - original (optional): If true, downloads original file instead of archived version
276
+
277
+ ```typescript
278
+ download_document({
279
+ id: 123,
280
+ original: false
281
+ })
282
+ ```
283
+
284
+ #### get_document_thumbnail
285
+ Get a document thumbnail (image preview) by ID. Returns the thumbnail as a base64-encoded WebP image resource.
286
+
287
+ Parameters:
288
+ - id: Document ID
289
+
290
+ ```typescript
291
+ get_document_thumbnail({
292
+ id: 123
293
+ })
294
+ ```
295
+
296
+ #### bulk_edit_documents
297
+ Perform bulk operations on multiple documents.
298
+
299
+ Parameters:
300
+ - documents: Array of document IDs
301
+ - method: One of:
302
+ - set_correspondent: Set correspondent for documents
303
+ - set_document_type: Set document type for documents
304
+ - set_storage_path: Set storage path for documents
305
+ - add_tag: Add a tag to documents
306
+ - remove_tag: Remove a tag from documents
307
+ - modify_tags: Add and/or remove multiple tags
308
+ - delete: Delete documents
309
+ - reprocess: Reprocess documents
310
+ - set_permissions: Set document permissions
311
+ - merge: Merge multiple documents
312
+ - split: Split a document into multiple documents
313
+ - rotate: Rotate document pages
314
+ - delete_pages: Delete specific pages from a document
315
+ - Additional parameters based on method:
316
+ - correspondent: ID for set_correspondent
317
+ - document_type: ID for set_document_type
318
+ - storage_path: ID for set_storage_path
319
+ - tag: ID for add_tag/remove_tag
320
+ - add_tags: Array of tag IDs for modify_tags
321
+ - remove_tags: Array of tag IDs for modify_tags
322
+ - set_permissions: Object for set_permissions with view/change users and groups (`{"view": {"users": [], "groups": []}, "change": {...}}`). Omitted actions/lists are left untouched
323
+ - owner: User ID (or null to remove) for set_permissions. Unless merge is true, omitting owner clears the current owner
324
+ - merge: Boolean for set_permissions — true adds to existing permissions and keeps the owner; false (default) replaces the listed users/groups
325
+ - metadata_document_id: ID for merge to specify metadata source
326
+ - delete_originals: Boolean for merge/split
327
+ - pages: String for split "[1,2-3,4,5-7]" or delete_pages "[2,3,4]"
328
+ - degrees: Number for rotate (90, 180, or 270)
329
+
330
+ Examples:
331
+ ```typescript
332
+ // Add a tag to multiple documents
333
+ bulk_edit_documents({
334
+ documents: [1, 2, 3],
335
+ method: "add_tag",
336
+ tag: 5
337
+ })
338
+
339
+ // Set correspondent and document type
340
+ bulk_edit_documents({
341
+ documents: [4, 5],
342
+ method: "set_correspondent",
343
+ correspondent: 2
344
+ })
345
+
346
+ // Merge documents
347
+ bulk_edit_documents({
348
+ documents: [6, 7, 8],
349
+ method: "merge",
350
+ metadata_document_id: 6,
351
+ delete_originals: true
352
+ })
353
+
354
+ // Split document into parts
355
+ bulk_edit_documents({
356
+ documents: [9],
357
+ method: "split",
358
+ pages: "[1-2,3-4,5]"
359
+ })
360
+
361
+ // Modify multiple tags at once
362
+ bulk_edit_documents({
363
+ documents: [10, 11],
364
+ method: "modify_tags",
365
+ add_tags: [1, 2],
366
+ remove_tags: [3, 4]
367
+ })
368
+
369
+ // Modify custom fields
370
+ bulk_edit_documents({
371
+ documents: [12, 13],
372
+ method: "modify_custom_fields",
373
+ add_custom_fields: [
374
+ { field: 2, value: "year" }
375
+ ],
376
+ remove_custom_fields: []
377
+ })
378
+
379
+ // Set an empty custom field value, e.g. a date field used as a pending marker
380
+ bulk_edit_documents({
381
+ documents: [14],
382
+ method: "modify_custom_fields",
383
+ add_custom_fields: [
384
+ { field: 9, value: "" }
385
+ ],
386
+ remove_custom_fields: []
387
+ })
388
+ ```
389
+
390
+ #### post_document
391
+ Upload a new document to Paperless-NGX.
392
+
393
+ **Two upload modes:**
394
+
395
+ 1. **Base64 mode** (traditional): Provide `file` (base64-encoded content) + `filename`
396
+ 2. **Filesystem mode** (efficient): Provide `file_path` (absolute path on server)
397
+
398
+ **Security Note:** When using `file_path`, set the `PAPERLESS_MCP_UPLOAD_PATHS` environment variable (colon-separated list of allowed directories) to restrict uploads to specific locations. Without this, any file on the server's filesystem could be uploaded.
399
+
400
+ Parameters:
401
+ - file (optional): Base64 encoded file content. Either `file` or `file_path` required.
402
+ - file_path (optional): Absolute path to file on server's filesystem. Either `file` or `file_path` required.
403
+ - filename (optional): Name of the file. Required with `file`, optional with `file_path` (derives from path).
404
+ - title (optional): Title for the document
405
+ - created (optional): DateTime when the document was created (e.g. "2024-01-19" or "2024-01-19 06:15:00+02:00")
406
+ - correspondent (optional): ID of a correspondent
407
+ - document_type (optional): ID of a document type
408
+ - storage_path (optional): ID of a storage path
409
+ - tags (optional): Array of tag IDs
410
+ - archive_serial_number (optional): Archive serial number
411
+ - custom_fields (optional): Array of custom field IDs
412
+
413
+ **File size limit:** 100MB for both modes
414
+
415
+ ```typescript
416
+ // Base64 mode (traditional)
417
+ post_document({
418
+ file: "base64_encoded_content",
419
+ filename: "invoice.pdf",
420
+ title: "January Invoice",
421
+ created: "2024-01-19",
422
+ correspondent: 1,
423
+ document_type: 2,
424
+ tags: [1, 3],
425
+ archive_serial_number: "2024-001",
426
+ custom_fields: [1, 2]
427
+ })
428
+
429
+ // Filesystem mode (more efficient for large files)
430
+ post_document({
431
+ file_path: "/var/uploads/invoice.pdf",
432
+ title: "January Invoice",
433
+ correspondent: 1,
434
+ document_type: 2,
435
+ tags: [1, 3]
436
+ })
437
+ ```
438
+
439
+ ### Document Notes
440
+
441
+ #### list_document_notes
442
+ List all notes attached to a document.
443
+
444
+ Parameters:
445
+ - id: Document ID
446
+
447
+ ```typescript
448
+ list_document_notes({
449
+ id: 123
450
+ })
451
+ ```
452
+
453
+ #### create_document_note
454
+ Add a note to a document. Returns the document's full list of notes.
455
+
456
+ Parameters:
457
+ - id: Document ID
458
+ - note: The note text to add
459
+
460
+ ```typescript
461
+ create_document_note({
462
+ id: 123,
463
+ note: "Invoice paid on 2026-06-30 from Commerzbank account."
464
+ })
465
+ ```
466
+
467
+ #### delete_document_note
468
+ ⚠️ Delete a single note from a document by its note ID. This operation is irreversible.
469
+
470
+ Parameters:
471
+ - id: Document ID
472
+ - note_id: The ID of the note to delete
473
+ - confirm: Must be `true` to confirm this destructive operation
474
+
475
+ ```typescript
476
+ delete_document_note({
477
+ id: 123,
478
+ note_id: 5,
479
+ confirm: true
480
+ })
481
+ ```
482
+
483
+ ### Tag Operations
484
+
485
+ #### list_tags
486
+ Get all tags.
487
+
488
+ ```typescript
489
+ list_tags()
490
+ ```
491
+
492
+ #### create_tag
493
+ Create a new tag.
494
+
495
+ Parameters:
496
+ - name: Tag name
497
+ - color (optional): Hex color code (e.g. "#ff0000")
498
+ - match (optional): Text pattern to match
499
+ - matching_algorithm (optional): Number between 0 and 6:
500
+ 0 - None
501
+ 1 - Any word
502
+ 2 - All words
503
+ 3 - Exact match
504
+ 4 - Regular expression
505
+ 5 - Fuzzy word
506
+ 6 - Automatic
507
+
508
+ ```typescript
509
+ create_tag({
510
+ name: "Invoice",
511
+ color: "#ff0000",
512
+ match: "invoice",
513
+ matching_algorithm: 5
514
+ })
515
+ ```
516
+
517
+ ### Correspondent Operations
518
+
519
+ #### list_correspondents
520
+ Get all correspondents.
521
+
522
+ ```typescript
523
+ list_correspondents()
524
+ ```
525
+
526
+ #### create_correspondent
527
+ Create a new correspondent.
528
+
529
+ Parameters:
530
+ - name: Correspondent name
531
+ - match (optional): Text pattern to match
532
+ - matching_algorithm (optional): Number between 0 and 6:
533
+ 0 - None
534
+ 1 - Any word
535
+ 2 - All words
536
+ 3 - Exact match
537
+ 4 - Regular expression
538
+ 5 - Fuzzy word
539
+ 6 - Automatic
540
+
541
+ ```typescript
542
+ create_correspondent({
543
+ name: "ACME Corp",
544
+ match: "ACME",
545
+ matching_algorithm: 5
546
+ })
547
+ ```
548
+
549
+ ### Document Type Operations
550
+
551
+ #### list_document_types
552
+ Get all document types.
553
+
554
+ ```typescript
555
+ list_document_types()
556
+ ```
557
+
558
+ #### create_document_type
559
+ Create a new document type.
560
+
561
+ Parameters:
562
+ - name: Document type name
563
+ - match (optional): Text pattern to match
564
+ - matching_algorithm (optional): Number between 0 and 6:
565
+ 0 - None
566
+ 1 - Any word
567
+ 2 - All words
568
+ 3 - Exact match
569
+ 4 - Regular expression
570
+ 5 - Fuzzy word
571
+ 6 - Automatic
572
+
573
+ ```typescript
574
+ create_document_type({
575
+ name: "Invoice",
576
+ match: "invoice total amount due",
577
+ matching_algorithm: 1
578
+ })
579
+ ```
580
+
581
+ ### Custom Field Operations
582
+
583
+ #### list_custom_fields
584
+ Get all custom fields.
585
+
586
+ ```typescript
587
+ list_custom_fields()
588
+ ```
589
+
590
+ #### get_custom_field
591
+ Get a specific custom field by ID.
592
+
593
+ Parameters:
594
+ - id: Custom field ID
595
+
596
+ ```typescript
597
+ get_custom_field({
598
+ id: 1
599
+ })
600
+ ```
601
+
602
+ #### create_custom_field
603
+ Create a new custom field.
604
+
605
+ Parameters:
606
+ - name: Custom field name
607
+ - data_type: One of "string", "url", "date", "boolean", "integer", "float", "monetary", "documentlink", "select"
608
+ - extra_data (optional): Extra data for the custom field, such as select options
609
+
610
+ ```typescript
611
+ create_custom_field({
612
+ name: "Invoice Number",
613
+ data_type: "string"
614
+ })
615
+ ```
616
+
617
+ #### update_custom_field
618
+ Update an existing custom field.
619
+
620
+ Parameters:
621
+ - id: Custom field ID
622
+ - name (optional): New custom field name
623
+ - data_type (optional): New data type
624
+ - extra_data (optional): Extra data for the custom field
625
+
626
+ ```typescript
627
+ update_custom_field({
628
+ id: 1,
629
+ name: "Updated Invoice Number",
630
+ data_type: "string"
631
+ })
632
+ ```
633
+
634
+ #### delete_custom_field
635
+ Delete a custom field.
636
+
637
+ Parameters:
638
+ - id: Custom field ID
639
+
640
+ ```typescript
641
+ delete_custom_field({
642
+ id: 1
643
+ })
644
+ ```
645
+
646
+ #### bulk_edit_custom_fields
647
+ Perform bulk operations on multiple custom fields.
648
+
649
+ Parameters:
650
+ - custom_fields: Array of custom field IDs
651
+ - operation: One of "delete"
652
+
653
+ ```typescript
654
+ bulk_edit_custom_fields({
655
+ custom_fields: [1, 2, 3],
656
+ operation: "delete"
657
+ })
658
+ ```
659
+
660
+ ### Mail Operations
661
+
662
+ Tools for managing Paperless mail accounts and the mail rules that drive
663
+ automatic email ingestion. Account passwords/tokens are never exposed: they are
664
+ redacted from every tool response.
665
+
666
+ #### list_mail_accounts
667
+ List mail accounts so you can pick the account ID needed when creating a mail
668
+ rule. Passwords are redacted.
669
+
670
+ Parameters:
671
+ - page (optional): Page number
672
+ - page_size (optional): Number of results per page
673
+
674
+ ```typescript
675
+ list_mail_accounts()
676
+ ```
677
+
678
+ #### get_mail_account
679
+ Get a single mail account by ID. Password/token fields are redacted.
680
+
681
+ Parameters:
682
+ - id: Mail account ID
683
+
684
+ ```typescript
685
+ get_mail_account({
686
+ id: 1
687
+ })
688
+ ```
689
+
690
+ #### process_mail_account
691
+ Manually trigger Paperless mail processing for one account. This can consume
692
+ matching mails according to the account's enabled mail rules.
693
+
694
+ Parameters:
695
+ - id: Mail account ID
696
+
697
+ ```typescript
698
+ process_mail_account({
699
+ id: 1
700
+ })
701
+ ```
702
+
703
+ #### list_mail_rules
704
+ List mail rules with optional pagination.
705
+
706
+ Parameters:
707
+ - page (optional): Page number
708
+ - page_size (optional): Number of results per page
709
+
710
+ ```typescript
711
+ list_mail_rules()
712
+ ```
713
+
714
+ #### get_mail_rule
715
+ Get a single mail rule by ID.
716
+
717
+ Parameters:
718
+ - id: Mail rule ID
719
+
720
+ ```typescript
721
+ get_mail_rule({
722
+ id: 1
723
+ })
724
+ ```
725
+
726
+ #### create_mail_rule
727
+ Create a mail rule. Use `list_mail_accounts` first to choose the account.
728
+
729
+ Required parameters:
730
+ - name: Rule name
731
+ - account: Mail account ID
732
+ - folder: IMAP folder to scan (e.g. "INBOX")
733
+
734
+ Common optional parameters:
735
+ - enabled (default true): Whether the rule is active
736
+ - filter_from / filter_to / filter_subject / filter_body: Match incoming mail
737
+ - maximum_age: Only process mail newer than this many days
738
+ - action: 1=Delete, 2=Move to folder, 3=Mark as read, 4=Flag, 5=Tag
739
+ - action_parameter: Target folder/tag for the chosen action
740
+ - assign_title_from: 1=Subject, 2=Attachment filename, 3=Do not assign
741
+ - assign_tags / assign_correspondent / assign_document_type: Metadata to apply
742
+ - assign_correspondent_from: 1=None, 2=Mail address, 3=Sender name, 4=Use assign_correspondent
743
+ - attachment_type: 1=Attachments only, 2=All files incl. inline
744
+ - consumption_scope: 1=Attachments only, 2=Full mail as .eml, 3=Both
745
+ - pdf_layout: 0=System default, 1=Text+HTML, 2=HTML+text, 3=HTML only, 4=Text only
746
+
747
+ ```typescript
748
+ create_mail_rule({
749
+ name: "Invoices",
750
+ account: 1,
751
+ folder: "INBOX",
752
+ filter_subject: "invoice",
753
+ action: 3,
754
+ attachment_type: 1
755
+ })
756
+ ```
757
+
758
+ #### update_mail_rule
759
+ Patch an existing mail rule. Only the fields you supply are changed.
760
+
761
+ Parameters:
762
+ - id: Mail rule ID
763
+ - ...any of the `create_mail_rule` fields to update
764
+
765
+ ```typescript
766
+ update_mail_rule({
767
+ id: 1,
768
+ enabled: false
769
+ })
770
+ ```
771
+
772
+ #### delete_mail_rule
773
+ Delete a mail rule. Requires an explicit confirmation flag. This changes future
774
+ mail ingestion behavior but does not delete any existing documents.
775
+
776
+ Parameters:
777
+ - id: Mail rule ID
778
+ - confirm: Must be `true` to confirm deletion
779
+
780
+ ```typescript
781
+ delete_mail_rule({
782
+ id: 1,
783
+ confirm: true
784
+ })
785
+ ```
786
+
787
+ ## Error Handling
788
+
789
+ The server will show clear error messages if:
790
+ - The Paperless-NGX URL or API token is incorrect
791
+ - The Paperless-NGX server is unreachable
792
+ - The requested operation fails
793
+ - The provided parameters are invalid
794
+
795
+ ## Testing
796
+
797
+ ### Unit tests
798
+
799
+ Run the unit test suite (no external dependencies required):
800
+
801
+ ```bash
802
+ npm test
803
+ ```
804
+
805
+ ### E2E tests
806
+
807
+ The E2E suite boots an empty Paperless-ngx instance, runs the compiled MCP server, and drives a deterministic serial scenario through `tools/call` requests — creating a tag, correspondent, and document type, uploading a PDF, then exercising list / get / search / download / thumbnail / bulk-edit on the same document. No LLM and no Paperless REST client outside MCP.
808
+
809
+ **Prerequisites:** Docker, Docker Compose, and `jq`.
810
+
811
+ ```bash
812
+ # 1. Build the MCP server
813
+ npm run build
814
+
815
+ # 2. Start Paperless-ngx
816
+ docker compose -f docker-compose.e2e.yml up -d
817
+
818
+ # 3. Wait for Paperless to be ready, then get a token
819
+ TOKEN=$(curl -s -X POST http://localhost:8000/api/token/ \
820
+ -H 'Content-Type: application/json' \
821
+ -d '{"username":"admin","password":"admin123"}' | jq -r '.token')
822
+
823
+ # 4. Start the MCP server
824
+ node build/index.js --http --port 3001 \
825
+ --baseUrl http://localhost:8000 --token "$TOKEN" &
826
+ MCP_PID=$!
827
+
828
+ # 5. Run the E2E tests
829
+ MCP_URL=http://localhost:3001/mcp \
830
+ PAPERLESS_URL=http://localhost:8000 \
831
+ PAPERLESS_TOKEN="$TOKEN" \
832
+ npm run test:e2e
833
+
834
+ # 6. Cleanup
835
+ kill "$MCP_PID"
836
+ docker compose -f docker-compose.e2e.yml down -v
837
+ ```
838
+
839
+ E2E tests also run automatically in CI on every pull request and push to `main`, covering both the `build/index.js` CLI and the published Docker image.
840
+
841
+ ## Development
842
+
843
+ Want to contribute or modify the server? Here's what you need to know:
844
+
845
+ 1. Clone the repository
846
+ 2. Install dependencies:
847
+ ```bash
848
+ npm install
849
+ ```
850
+
851
+ 3. Make your changes to server.js
852
+ 4. Test locally:
853
+ ```bash
854
+ node server.js http://localhost:8000 your-test-token
855
+ ```
856
+
857
+ The server is built with:
858
+ - [litemcp](https://github.com/wong2/litemcp): A TypeScript framework for building MCP servers
859
+ - [zod](https://github.com/colinhacks/zod): TypeScript-first schema validation
860
+
861
+ ## API Documentation
862
+
863
+ This MCP server implements endpoints from the Paperless-NGX REST API. For more details about the underlying API, see the [official documentation](https://docs.paperless-ngx.com/api/).
864
+
865
+ ## Running the MCP Server
866
+
867
+ The MCP server can be run in two modes:
868
+
869
+ ### 1. stdio (default)
870
+
871
+ This is the default mode. The server communicates over stdio, suitable for CLI and direct integrations.
872
+
873
+ ```
874
+ npm run start -- <baseUrl> <token>
875
+ ```
876
+
877
+ ### 2. HTTP (Streamable HTTP Transport)
878
+
879
+ 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](https://expressjs.com/) to be installed (it is included as a dependency).
880
+
881
+ ```
882
+ npm run start -- <baseUrl> <token> --http --port 3000
883
+ ```
884
+
885
+ - The MCP API will be available at `POST /mcp` on the specified port.
886
+ - Each request is handled statelessly, following the [StreamableHTTPServerTransport](https://github.com/modelcontextprotocol/typescript-sdk) pattern.
887
+ - GET and DELETE requests to `/mcp` will return 405 Method Not Allowed.
888
+
889
+ #### Per-request API token (HTTP/Docker mode)
890
+
891
+ In HTTP mode, clients authenticate by supplying a Paperless-NGX API token via the standard `Authorization` header:
892
+
893
+ ```
894
+ Authorization: Bearer <paperless-ngx-api-token>
895
+ ```
896
+
897
+ The token is passed straight through to Paperless-NGX, so each client's own Paperless permissions are enforced end-to-end. This lets a single server instance serve multiple users, each with their own token. The same behaviour applies to both `/mcp` and `/sse` endpoints.
898
+
899
+ > **⚠️ Breaking change in v2.0.0 — HTTP mode is now authenticated by default.**
900
+ >
901
+ > Previously, a request with no `Authorization` header silently fell back to the server-configured `PAPERLESS_API_KEY`, which left the HTTP endpoint open to anyone who could reach the port. As of v2.0.0, requests without a `Bearer` token are rejected with `401 Unauthorized`. The server token is **never** used for unauthenticated requests unless you explicitly opt in with `--no-auth`.
902
+
903
+ | Scenario | `--no-auth` off (default) | `--no-auth` on |
904
+ |---|---|---|
905
+ | Client sends `Authorization: Bearer <tok>` | `<tok>` (client-supplied) | `<tok>` (client-supplied) |
906
+ | No header, `PAPERLESS_API_KEY` / `--token` set | `401 Unauthorized` | server token |
907
+ | No header, no server token | `401 Unauthorized` | `401 Unauthorized` |
908
+
909
+ **Migrating from v1.x:** if you relied on the old fallback (a single shared `PAPERLESS_API_KEY` with clients that don't send a token), you have two options:
910
+
911
+ 1. **Recommended:** have each client send `Authorization: Bearer <paperless-token>`.
912
+ 2. **Restore the old behaviour** (trusted/local networks only): start the server with the `--no-auth` flag, e.g. append it to the Docker `command`/args or your CLI invocation. This requires a server token (`PAPERLESS_API_KEY` or `--token`) to be configured.
913
+
914
+ <details>
915
+ <summary>Docker Deployment</summary>
916
+
917
+ The MCP server can be deployed using Docker and Docker Compose. The Docker image automatically runs in HTTP mode with SSE (Server-Sent Events) support on port 3000.
918
+
919
+ ### Docker Compose Configuration
920
+
921
+ Create a `docker-compose.yml` file:
922
+
923
+ ```yaml
924
+ services:
925
+ paperless-mcp:
926
+ container_name: paperless-mcp
927
+ image: ghcr.io/retiform-labs/paperless-mcp:latest
928
+ environment:
929
+ - PAPERLESS_URL=http://your-paperless-ngx-server:8000
930
+ - PAPERLESS_API_KEY=your-paperless-api-key
931
+ - PAPERLESS_PUBLIC_URL=https://paperless-ngx.yourpublicurl.com
932
+ ports:
933
+ - "3000:3000"
934
+ restart: unless-stopped
935
+ ```
936
+
937
+ Then run:
938
+ ```bash
939
+ docker-compose up -d
940
+ ```
941
+
942
+ ### Using with Continue VS Code Extension
943
+
944
+ If you're using the [Continue VS Code extension](https://continue.dev/), you can configure it to use the Dockerized MCP server via SSE.
945
+
946
+ Create or edit `.continue/mcpServers/paperless-mcp.yaml` at your workspace root:
947
+
948
+ ```yaml
949
+ name: Paperless
950
+ version: 0.0.1
951
+ schema: v1
952
+ mcpServers:
953
+ - name: Paperless
954
+ type: sse
955
+ url: http://localhost:3000/sse
956
+ ```
957
+
958
+ **Notes:**
959
+ - Replace `localhost` with your Docker host's IP address or hostname if running on a remote server
960
+ - The Docker container handles authentication via environment variables, so no credentials are needed in the Continue config
961
+ - The SSE endpoint is available at `/sse` on the configured port (default: 3000)
962
+
963
+ </details>
964
+
965
+ # Credits
966
+
967
+ This project is a fork of [nloui/paperless-mcp](https://github.com/nloui/paperless-mcp). Many thanks to the original author for their work. Contributions and improvements may be returned upstream.
968
+
969
+ ## Debugging
970
+
971
+ To debug the MCP server in VS Code, use the following launch configuration:
972
+
973
+ ```json
974
+ {
975
+ "type": "node",
976
+ "request": "launch",
977
+ "name": "Debug Paperless MCP (HTTP, ts-node ESM)",
978
+ "program": "${workspaceFolder}/node_modules/ts-node/dist/bin.js",
979
+ "args": [
980
+ "--esm",
981
+ "src/index.ts",
982
+ "--http",
983
+ "--baseUrl",
984
+ "http://your-paperless-instance:8000",
985
+ "--token",
986
+ "your-api-token",
987
+ "--port",
988
+ "3002"
989
+ ],
990
+ "env": {
991
+ "NODE_OPTIONS": "--loader ts-node/esm",
992
+ },
993
+ "console": "integratedTerminal",
994
+ "skipFiles": [
995
+ "<node_internals>/**"
996
+ ]
997
+ }
998
+ ```
999
+
1000
+ **Important:** Before debugging, uncomment the following line in `src/index.ts` (around line 175):
1001
+
1002
+ ```typescript
1003
+ // await new Promise((resolve) => setTimeout(resolve, 1000000));
1004
+ ```
1005
+
1006
+ This prevents the server from exiting immediately and allows you to set breakpoints and debug the code.