@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.
- package/LICENSE +18 -0
- package/README.md +1005 -2
- package/build/api/PaperlessAPI.d.ts +63 -0
- package/build/api/PaperlessAPI.js +405 -0
- package/build/api/documentEnhancer.d.ts +24 -0
- package/build/api/documentEnhancer.js +111 -0
- package/build/api/documentEnhancer.test.d.ts +1 -0
- package/build/api/documentEnhancer.test.js +80 -0
- package/build/api/types.d.ts +203 -0
- package/build/api/types.js +15 -0
- package/build/api/utils.d.ts +16 -0
- package/build/api/utils.js +29 -0
- package/build/index.d.ts +2 -0
- package/build/index.js +189 -0
- package/build/resources/documents.d.ts +7 -0
- package/build/resources/documents.js +119 -0
- package/build/resources/documents.test.d.ts +1 -0
- package/build/resources/documents.test.js +124 -0
- package/build/server.d.ts +24 -0
- package/build/server.js +70 -0
- package/build/server.test.d.ts +1 -0
- package/build/server.test.js +54 -0
- package/build/test/mocks/paperlessApi.d.ts +4 -0
- package/build/test/mocks/paperlessApi.js +33 -0
- package/build/tools/boundedContent.test.d.ts +1 -0
- package/build/tools/boundedContent.test.js +544 -0
- package/build/tools/correspondents.d.ts +3 -0
- package/build/tools/correspondents.js +149 -0
- package/build/tools/customFields.d.ts +3 -0
- package/build/tools/customFields.js +142 -0
- package/build/tools/documentTypes.d.ts +3 -0
- package/build/tools/documentTypes.js +143 -0
- package/build/tools/documents.d.ts +134 -0
- package/build/tools/documents.js +814 -0
- package/build/tools/documents.test.d.ts +1 -0
- package/build/tools/documents.test.js +658 -0
- package/build/tools/mail.d.ts +3 -0
- package/build/tools/mail.js +187 -0
- package/build/tools/mail.test.d.ts +1 -0
- package/build/tools/mail.test.js +212 -0
- package/build/tools/notes.d.ts +3 -0
- package/build/tools/notes.js +55 -0
- package/build/tools/notes.test.d.ts +1 -0
- package/build/tools/notes.test.js +177 -0
- package/build/tools/schemaCompat.test.d.ts +1 -0
- package/build/tools/schemaCompat.test.js +59 -0
- package/build/tools/tags.d.ts +3 -0
- package/build/tools/tags.js +143 -0
- package/build/tools/utils/descriptions.d.ts +1 -0
- package/build/tools/utils/descriptions.js +4 -0
- package/build/tools/utils/documentQuery.d.ts +71 -0
- package/build/tools/utils/documentQuery.js +270 -0
- package/build/tools/utils/empty.d.ts +2 -0
- package/build/tools/utils/empty.js +7 -0
- package/build/tools/utils/matchingAlgorithm.d.ts +2 -0
- package/build/tools/utils/matchingAlgorithm.js +15 -0
- package/build/tools/utils/middlewares.d.ts +3 -0
- package/build/tools/utils/middlewares.js +31 -0
- package/build/tools/utils/monetary.d.ts +5 -0
- package/build/tools/utils/monetary.js +34 -0
- package/build/tools/utils/monetary.test.d.ts +1 -0
- package/build/tools/utils/monetary.test.js +25 -0
- package/build/tools/utils/queryString.d.ts +1 -0
- package/build/tools/utils/queryString.js +12 -0
- package/build/tools/utils/resourceUri.d.ts +29 -0
- package/build/tools/utils/resourceUri.js +37 -0
- package/build/tools/utils/resourceUri.test.d.ts +1 -0
- package/build/tools/utils/resourceUri.test.js +50 -0
- package/build/tools/utils/selectFields.d.ts +13 -0
- package/build/tools/utils/selectFields.js +91 -0
- package/build/tools/utils/selectFields.test.d.ts +1 -0
- package/build/tools/utils/selectFields.test.js +164 -0
- package/package.json +59 -4
- package/paperless-mcp.dxt +0 -0
package/README.md
CHANGED
|
@@ -1,3 +1,1006 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- [](https://mseep.ai/app/nloui-paperless-mcp) -->
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# Paperless-NGX MCP Server
|
|
4
|
+
|
|
5
|
+

|
|
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
|
+
[](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.
|