Skip to content
Back to search

paperless-mcp

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/baruchiro/paperless-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/baruchiro/paperless-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/baruchiro--paperless-mcp/badge.svg)](/listings/baruchiro--paperless-mcp)

HTML

<a href="/listings/baruchiro--paperless-mcp"><img src="/api/listings/baruchiro--paperless-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installation

Add these to your MCP config file:

// STDIO mode (recommended for local or CLI use)

"paperless": {
  "command": "npx",
  "args": [
    "-y",
    "@baruchiro/paperless-mcp@latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

// HTTP mode (recommended for Docker or remote use)

"paperless": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/baruchiro/paperless-mcp:latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

3. Get your API token: 1. Log into your Paperless-NGX instance 2. Click your username in the top right 3. Select "My Profile" 4. Click the circular arrow button to generate a new token

4. Replace the placeholders in your MCP config: - `http://your-paperless-instance:8000` with your Paperless-NGX URL - `your-api-token` with the token you just generated - `https://your-public-domain.com` with your public Paperless-NGX URL (optional, falls back to PAPERLESS_URL)

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | `PAPERLESS_URL` | Yes | — | Base URL of your Paperless-NGX instance | | `PAPERLESS_API_KEY` | Yes | — | API token from your Paperless-NGX profile | | `PAPERLESS_PUBLIC_URL` | No | `PAPERLESS_URL` | Public-facing URL for document links | | `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. | | `PAPERLESS_MCP_UPLOAD_PATHS` | No | — | Colon-separated list of allowed directories for `file_path` uploads. **Recommended for security.** Example: `/var/uploads:/tmp/scans` |

That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.

Example Usage

Here are some things you can ask Claude to do:

- "Show me all documents tagged as 'Invoice'" - "Search for documents containing 'tax return'" - "Create a new tag called 'Receipts' with color #FF0000" - "Download document #123" - "List all correspondents" - "Create a new document type called 'Bank Statement'"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 979 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/nloui-paperless-mcp-badge.png)](https://mseep.ai/app/nloui-paperless-mcp) -->
  2. # Paperless-NGX MCP Server
  3. ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/baruchiro/paperless-mcp?utm_source=oss&utm_medium=github&utm_campaign=baruchiro%2Fpaperless-mcp&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
  4. 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.
  5. ## Quick Start
  6. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=paperless&config=eyJjb21tYW5kIjoibnB4IC15IEBiYXJ1Y2hpcm8vcGFwZXJsZXNzLW1jcEBsYXRlc3QiLCJlbnYiOnsiUEFQRVJMRVNTX1VSTCI6Imh0dHA6Ly95b3VyLXBhcGVybGVzcy1pbnN0YW5jZTo4MDAwIiwiUEFQRVJMRVNTX0FQSV9LRVkiOiJ5b3VyLWFwaS10b2tlbiJ9fQ%3D%3D)
  7. ### Installation
  8. Add these to your MCP config file:
  9. // STDIO mode (recommended for local or CLI use)
  10. ```json
  11. "paperless": {
  12. "command": "npx",
  13. "args": [
  14. "-y",
  15. "@baruchiro/paperless-mcp@latest",
  16. ],
  17. "env": {
  18. "PAPERLESS_URL": "http://your-paperless-instance:8000",
  19. "PAPERLESS_API_KEY": "your-api-token",
  20. "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  21. }
  22. }
  23. ```
  24. // HTTP mode (recommended for Docker or remote use)
  25. ```json
  26. "paperless": {
  27. "command": "docker",
  28. "args": [
  29. "run",
  30. "-i",
  31. "--rm",
  32. "ghcr.io/baruchiro/paperless-mcp:latest",
  33. ],
  34. "env": {
  35. "PAPERLESS_URL": "http://your-paperless-instance:8000",
  36. "PAPERLESS_API_KEY": "your-api-token",
  37. "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  38. }
  39. }
  40. ```
  41. 3. Get your API token:
  42. 1. Log into your Paperless-NGX instance
  43. 2. Click your username in the top right
  44. 3. Select "My Profile"
  45. 4. Click the circular arrow button to generate a new token
  46. 4. Replace the placeholders in your MCP config:
  47. - `http://your-paperless-instance:8000` with your Paperless-NGX URL
  48. - `your-api-token` with the token you just generated
  49. - `https://your-public-domain.com` with your public Paperless-NGX URL (optional, falls back to PAPERLESS_URL)
  50. ### Environment Variables
  51. | Variable | Required | Default | Description |
  52. |---|---|---|---|
  53. | `PAPERLESS_URL` | Yes | — | Base URL of your Paperless-NGX instance |
  54. | `PAPERLESS_API_KEY` | Yes | — | API token from your Paperless-NGX profile |
  55. | `PAPERLESS_PUBLIC_URL` | No | `PAPERLESS_URL` | Public-facing URL for document links |
  56. | `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. |
  57. | `PAPERLESS_MCP_UPLOAD_PATHS` | No | — | Colon-separated list of allowed directories for `file_path` uploads. **Recommended for security.** Example: `/var/uploads:/tmp/scans` |
  58. That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.
  59. ### Example Usage
  60. Here are some things you can ask Claude to do:
  61. - "Show me all documents tagged as 'Invoice'"
  62. - "Search for documents containing 'tax return'"
  63. - "Create a new tag called 'Receipts' with color #FF0000"
  64. - "Download document #123"
  65. - "List all correspondents"
  66. - "Create a new document type called 'Bank Statement'"
  67. ## Available Tools
  68. ### Document Operations
  69. #### list_documents
  70. 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`.
  71. Parameters:
  72. - page (optional): Page number
  73. - page_size (optional): Number of documents per page
  74. - search (optional): Simple Paperless search term
  75. - correspondent (optional): Correspondent ID
  76. - document_type (optional): Document type ID
  77. - tag (optional): Tag ID
  78. - storage_path (optional): Storage path ID
  79. - created__date__gte (optional): Created date on or after YYYY-MM-DD
  80. - created__date__lte (optional): Created date on or before YYYY-MM-DD
  81. - ordering (optional): Paperless ordering field
  82. - archive_serial_number (optional): Archive serial number
  83. - archive_serial_number__isnull (optional): Whether the archive serial number is empty
  84. - custom_field_query (optional): Raw JSON-encoded Paperless custom field query string
  85. - custom_fields__icontains (optional): Case-insensitive substring match across custom field values
  86. ```typescript
  87. list_documents({
  88. page: 1,
  89. page_size: 25
  90. })
  91. ```
  92. #### query_documents
  93. Canonical document query tool. Supports full-text querying, simple Paperless search, custom field filters, and documented `/api/documents/` Paperless query parameters.
  94. Parameters:
  95. - page (optional): Page number
  96. - page_size (optional): Number of documents per page
  97. - ordering (optional): Paperless ordering field
  98. - query (optional): Full-text query string
  99. - search (optional): Simple Paperless search term
  100. - more_like_id (optional): Find documents similar to this document ID
  101. - correspondent (optional): Correspondent ID
  102. - document_type (optional): Document type ID
  103. - tag (optional): Tag ID
  104. - storage_path (optional): Storage path ID
  105. - created__date__gte (optional): Created date on or after YYYY-MM-DD
  106. - created__date__lte (optional): Created date on or before YYYY-MM-DD
  107. - custom_field_query (optional): Structured Paperless custom field query using `[field_name_or_id, operator, value]` leaves or `["AND" | "OR", [clause1, clause2]]` groups
  108. - paperless_filters (optional): Additional documented `/api/documents/` Paperless query parameters, passed as key/value pairs
  109. ```typescript
  110. // Full-text query
  111. query_documents({
  112. query: "invoice 2024"
  113. })
  114. // Simple search term
  115. query_documents({
  116. search: "acme"
  117. })
  118. // Custom field exact match
  119. query_documents({
  120. custom_field_query: ["Invoice Number", "exact", "12345"]
  121. })
  122. // Custom field empty
  123. query_documents({
  124. custom_field_query: ["OR", [
  125. ["Invoice Number", "isnull", true],
  126. ["Invoice Number", "exact", ""]
  127. ]]
  128. })
  129. // Custom field missing
  130. query_documents({
  131. custom_field_query: ["Invoice Number", "exists", false]
  132. })
  133. // Combined filters
  134. query_documents({
  135. query: "invoice",
  136. tag: 5,
  137. created__date__gte: "2024-01-01",
  138. custom_field_query: ["Invoice Number", "exists", true]
  139. })
  140. // One documented Paperless filter that is not a first-class argument
  141. query_documents({
  142. paperless_filters: {
  143. id__in: [101, 202, 303]
  144. }
  145. })
  146. ```
  147. #### get_document
  148. Get a specific document by ID.
  149. Parameters:
  150. - id: Document ID
  151. ```typescript
  152. get_document({
  153. id: 123
  154. })
  155. ```
  156. #### search_documents
  157. Deprecated compatibility wrapper for full-text search. Prefer `query_documents({ query: ... })` for new integrations.
  158. Parameters:
  159. - query: Search query string
  160. ```typescript
  161. search_documents({
  162. query: "invoice 2024"
  163. })
  164. ```
  165. #### download_document
  166. Download a document file by ID.
  167. Parameters:
  168. - id: Document ID
  169. - original (optional): If true, downloads original file instead of archived version
  170. ```typescript
  171. download_document({
  172. id: 123,
  173. original: false
  174. })
  175. ```
  176. #### get_document_thumbnail
  177. Get a document thumbnail (image preview) by ID. Returns the thumbnail as a base64-encoded WebP image resource.
  178. Parameters:
  179. - id: Document ID
  180. ```typescript
  181. get_document_thumbnail({
  182. id: 123
  183. })
  184. ```
  185. #### bulk_edit_documents
  186. Perform bulk operations on multiple documents.
  187. Parameters:
  188. - documents: Array of document IDs
  189. - method: One of:
  190. - set_correspondent: Set correspondent for documents
  191. - set_document_type: Set document type for documents
  192. - set_storage_path: Set storage path for documents
  193. - add_tag: Add a tag to documents
  194. - remove_tag: Remove a tag from documents
  195. - modify_tags: Add and/or remove multiple tags
  196. - delete: Delete documents
  197. - reprocess: Reprocess documents
  198. - set_permissions: Set document permissions
  199. - merge: Merge multiple documents
  200. - split: Split a document into multiple documents
  201. - rotate: Rotate document pages
  202. - delete_pages: Delete specific pages from a document
  203. - Additional parameters based on method:
  204. - correspondent: ID for set_correspondent
  205. - document_type: ID for set_document_type
  206. - storage_path: ID for set_storage_path
  207. - tag: ID for add_tag/remove_tag
  208. - add_tags: Array of tag IDs for modify_tags
  209. - remove_tags: Array of tag IDs for modify_tags
  210. - set_permissions: Object for set_permissions with view/change users and groups (`{"view": {"users": [], "groups": []}, "change": {...}}`). Omitted actions/lists are left untouched
  211. - owner: User ID (or null to remove) for set_permissions. Unless merge is true, omitting owner clears the current owner
  212. - merge: Boolean for set_permissions — true adds to existing permissions and keeps the owner; false (default) replaces the listed users/groups
  213. - metadata_document_id: ID for merge to specify metadata source
  214. - delete_originals: Boolean for merge/split
  215. - pages: String for split "[1,2-3,4,5-7]" or delete_pages "[2,3,4]"
  216. - degrees: Number for rotate (90, 180, or 270)
  217. Examples:
  218. ```typescript
  219. // Add a tag to multiple documents
  220. bulk_edit_documents({
  221. documents: [1, 2, 3],
  222. method: "add_tag",
  223. tag: 5
  224. })
  225. // Set correspondent and document type
  226. bulk_edit_documents({
  227. documents: [4, 5],
  228. method: "set_correspondent",
  229. correspondent: 2
  230. })
  231. // Merge documents
  232. bulk_edit_documents({
  233. documents: [6, 7, 8],
  234. method: "merge",
  235. metadata_document_id: 6,
  236. delete_originals: true
  237. })
  238. // Split document into parts
  239. bulk_edit_documents({
  240. documents: [9],
  241. method: "split",
  242. pages: "[1-2,3-4,5]"
  243. })
  244. // Modify multiple tags at once
  245. bulk_edit_documents({
  246. documents: [10, 11],
  247. method: "modify_tags",
  248. add_tags: [1, 2],
  249. remove_tags: [3, 4]
  250. })
  251. // Modify custom fields
  252. bulk_edit_documents({
  253. documents: [12, 13],
  254. method: "modify_custom_fields",
  255. add_custom_fields: [
  256. { field: 2, value: "year" }
  257. ],
  258. remove_custom_fields: []
  259. })
  260. // Set an empty custom field value, e.g. a date field used as a pending marker
  261. bulk_edit_documents({
  262. documents: [14],
  263. method: "modify_custom_fields",
  264. add_custom_fields: [
  265. { field: 9, value: "" }
  266. ],
  267. remove_custom_fields: []
  268. })
  269. ```
  270. #### post_document
  271. Upload a new document to Paperless-NGX.
  272. **Two upload modes:**
  273. 1. **Base64 mode** (traditional): Provide `file` (base64-encoded content) + `filename`
  274. 2. **Filesystem mode** (efficient): Provide `file_path` (absolute path on server)
  275. **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.
  276. Parameters:
  277. - file (optional): Base64 encoded file content. Either `file` or `file_path` required.
  278. - file_path (optional): Absolute path to file on server's filesystem. Either `file` or `file_path` required.
  279. - filename (optional): Name of the file. Required with `file`, optional with `file_path` (derives from path).
  280. - title (optional): Title for the document
  281. - created (optional): DateTime when the document was created (e.g. "2024-01-19" or "2024-01-19 06:15:00+02:00")
  282. - correspondent (optional): ID of a correspondent
  283. - document_type (optional): ID of a document type
  284. - storage_path (optional): ID of a storage path
  285. - tags (optional): Array of tag IDs
  286. - archive_serial_number (optional): Archive serial number
  287. - custom_fields (optional): Array of custom field IDs
  288. **File size limit:** 100MB for both modes
  289. ```typescript
  290. // Base64 mode (traditional)
  291. post_document({
  292. file: "base64_encoded_content",
  293. filename: "invoice.pdf",
  294. title: "January Invoice",
  295. created: "2024-01-19",
  296. correspondent: 1,
  297. document_type: 2,
  298. tags: [1, 3],
  299. archive_serial_number: "2024-001",
  300. custom_fields: [1, 2]
  301. })
  302. // Filesystem mode (more efficient for large files)
  303. post_document({
  304. file_path: "/var/uploads/invoice.pdf",
  305. title: "January Invoice",
  306. correspondent: 1,
  307. document_type: 2,
  308. tags: [1, 3]
  309. })
  310. ```
  311. ### Document Notes
  312. #### list_document_notes
  313. List all notes attached to a document.
  314. Parameters:
  315. - id: Document ID
  316. ```typescript
  317. list_document_notes({
  318. id: 123
  319. })
  320. ```
  321. #### create_document_note
  322. Add a note to a document. Returns the document's full list of notes.
  323. Parameters:
  324. - id: Document ID
  325. - note: The note text to add
  326. ```typescript
  327. create_document_note({
  328. id: 123,
  329. note: "Invoice paid on 2026-06-30 from Commerzbank account."
  330. })
  331. ```
  332. #### delete_document_note
  333. ⚠️ Delete a single note from a document by its note ID. This operation is irreversible.
  334. Parameters:
  335. - id: Document ID
  336. - note_id: The ID of the note to delete
  337. - confirm: Must be `true` to confirm this destructive operation
  338. ```typescript
  339. delete_document_note({
  340. id: 123,
  341. note_id: 5,
  342. confirm: true
  343. })
  344. ```
  345. ### Tag Operations
  346. #### list_tags
  347. Get all tags.
  348. ```typescript
  349. list_tags()
  350. ```
  351. #### create_tag
  352. Create a new tag.
  353. Parameters:
  354. - name: Tag name
  355. - color (optional): Hex color code (e.g. "#ff0000")
  356. - match (optional): Text pattern to match
  357. - matching_algorithm (optional): Number between 0 and 6:
  358. 0 - None
  359. 1 - Any word
  360. 2 - All words
  361. 3 - Exact match
  362. 4 - Regular expression
  363. 5 - Fuzzy word
  364. 6 - Automatic
  365. ```typescript
  366. create_tag({
  367. name: "Invoice",
  368. color: "#ff0000",
  369. match: "invoice",
  370. matching_algorithm: 5
  371. })
  372. ```
  373. ### Storage Path Operations
  374. #### list_storage_paths
  375. List one page of storage paths, including IDs, names, path templates and matching rules. This is a read-only operation; it does not create paths or modify documents.
  376. Optional parameters: `page`, `page_size` (positive integers), `id`, `id__in` (integer array), `full_perms`, `ordering`, and the `icontains`, `iendswith`, `iexact`, `istartswith` filters for `name` and `path` (e.g. `name__icontains`).
  377. Returns the API pagination envelope (`count`, `results`, and available `next`, `previous`, `all` fields). Use `page` to request subsequent pages; matching algorithms retain their numeric API values.
  378. ```typescript
  379. list_storage_paths({ page: 1, page_size: 100, name__icontains: "Invoices" })
  380. ```
  381. ### Task Operations
  382. #### list_tasks
  383. List Paperless consumer-queue tasks, including uploads that failed to consume (unsupported file type, duplicate of an existing document, unreadable file). The failure reason is in each task's `result`.
  384. Optional parameters: `acknowledged` (boolean), `status` (`failure`, `pending`, `received`, `retry`, `revoked`, `started`, `success`; sent in the casing Paperless 3.x expects, retried in uppercase for Paperless 2.x), `task_name` (`consume_file`, `train_classifier`, `check_sanity`, `index_optimize`), `type` (`auto_task`, `scheduled_task`, `manual_task`).
  385. Returns the array of tasks as returned by Paperless (`id`, `task_file_name`, `status`, `result`, `related_document`, dates, `acknowledged`). `task_file_name` and `related_document` can be `null` for tasks that are not uploads.
  386. On Paperless-ngx 2.14.7, which only supports up to API version 7 (set `PAPERLESS_API_VERSION=7`), the filters are ignored and acknowledged tasks are not returned.
  387. ```typescript
  388. list_tasks({ status: "failure", acknowledged: false })
  389. ```
  390. #### acknowledge_tasks
  391. Mark tasks as acknowledged by their numeric IDs from `list_tasks`. This only sets the `acknowledged` flag; it does not delete or retry tasks.
  392. Parameters:
  393. - tasks: Array of task IDs
  394. Returns `{ "result": <number of tasks acknowledged> }`.
  395. ```typescript
  396. acknowledge_tasks({ tasks: [12, 13] })
  397. ```
  398. ### Correspondent Operations
  399. #### list_correspondents
  400. Get all correspondents.
  401. ```typescript
  402. list_correspondents()
  403. ```
  404. #### create_correspondent
  405. Create a new correspondent.
  406. Parameters:
  407. - name: Correspondent name
  408. - match (optional): Text pattern to match
  409. - matching_algorithm (optional): Number between 0 and 6:
  410. 0 - None
  411. 1 - Any word
  412. 2 - All words
  413. 3 - Exact match
  414. 4 - Regular expression
  415. 5 - Fuzzy word
  416. 6 - Automatic
  417. ```typescript
  418. create_correspondent({
  419. name: "ACME Corp",
  420. match: "ACME",
  421. matching_algorithm: 5
  422. })
  423. ```
  424. ### Document Type Operations
  425. #### list_document_types
  426. Get all document types.
  427. ```typescript
  428. list_document_types()
  429. ```
  430. #### create_document_type
  431. Create a new document type.
  432. Parameters:
  433. - name: Document type name
  434. - match (optional): Text pattern to match
  435. - matching_algorithm (optional): Number between 0 and 6:
  436. 0 - None
  437. 1 - Any word
  438. 2 - All words
  439. 3 - Exact match
  440. 4 - Regular expression
  441. 5 - Fuzzy word
  442. 6 - Automatic
  443. ```typescript
  444. create_document_type({
  445. name: "Invoice",
  446. match: "invoice total amount due",
  447. matching_algorithm: 1
  448. })
  449. ```
  450. ### Custom Field Operations
  451. #### list_custom_fields
  452. Get all custom fields.
  453. ```typescript
  454. list_custom_fields()
  455. ```
  456. #### get_custom_field
  457. Get a specific custom field by ID.
  458. Parameters:
  459. - id: Custom field ID
  460. ```typescript
  461. get_custom_field({
  462. id: 1
  463. })
  464. ```
  465. #### create_custom_field
  466. Create a new custom field.
  467. Parameters:
  468. - name: Custom field name
  469. - data_type: One of "string", "url", "date", "boolean", "integer", "float", "monetary", "documentlink", "select"
  470. - extra_data (optional): Extra data for the custom field, such as select options
  471. ```typescript
  472. create_custom_field({
  473. name: "Invoice Number",
  474. data_type: "string"
  475. })
  476. ```
  477. #### update_custom_field
  478. Update an existing custom field.
  479. Parameters:
  480. - id: Custom field ID
  481. - name (optional): New custom field name
  482. - data_type (optional): New data type
  483. - extra_data (optional): Extra data for the custom field
  484. ```typescript
  485. update_custom_field({
  486. id: 1,
  487. name: "Updated Invoice Number",
  488. data_type: "string"
  489. })
  490. ```
  491. #### delete_custom_field
  492. Delete a custom field.
  493. Parameters:
  494. - id: Custom field ID
  495. ```typescript
  496. delete_custom_field({
  497. id: 1
  498. })
  499. ```
  500. #### bulk_edit_custom_fields
  501. Perform bulk operations on multiple custom fields.
  502. Parameters:
  503. - custom_fields: Array of custom field IDs
  504. - operation: One of "delete"
  505. ```typescript
  506. bulk_edit_custom_fields({
  507. custom_fields: [1, 2, 3],
  508. operation: "delete"
  509. })
  510. ```
  511. ### Mail Operations
  512. Tools for managing Paperless mail accounts and the mail rules that drive
  513. automatic email ingestion. Account passwords/tokens are never exposed: they are
  514. redacted from every tool response.
  515. #### list_mail_accounts
  516. List mail accounts so you can pick the account ID needed when creating a mail
  517. rule. Passwords are redacted.
  518. Parameters:
  519. - page (optional): Page number
  520. - page_size (optional): Number of results per page
  521. ```typescript
  522. list_mail_accounts()
  523. ```
  524. #### get_mail_account
  525. Get a single mail account by ID. Password/token fields are redacted.
  526. Parameters:
  527. - id: Mail account ID
  528. ```typescript
  529. get_mail_account({
  530. id: 1
  531. })
  532. ```
  533. #### process_mail_account
  534. Manually trigger Paperless mail processing for one account. This can consume
  535. matching mails according to the account's enabled mail rules.
  536. Parameters:
  537. - id: Mail account ID
  538. ```typescript
  539. process_mail_account({
  540. id: 1
  541. })
  542. ```
  543. #### list_mail_rules
  544. List mail rules with optional pagination.
  545. Parameters:
  546. - page (optional): Page number
  547. - page_size (optional): Number of results per page
  548. ```typescript
  549. list_mail_rules()
  550. ```
  551. #### get_mail_rule
  552. Get a single mail rule by ID.
  553. Parameters:
  554. - id: Mail rule ID
  555. ```typescript
  556. get_mail_rule({
  557. id: 1
  558. })
  559. ```
  560. #### create_mail_rule
  561. Create a mail rule. Use `list_mail_accounts` first to choose the account.
  562. Required parameters:
  563. - name: Rule name
  564. - account: Mail account ID
  565. - folder: IMAP folder to scan (e.g. "INBOX")
  566. Common optional parameters:
  567. - enabled (default true): Whether the rule is active
  568. - filter_from / filter_to / filter_subject / filter_body: Match incoming mail
  569. - maximum_age: Only process mail newer than this many days
  570. - action: 1=Delete, 2=Move to folder, 3=Mark as read, 4=Flag, 5=Tag
  571. - action_parameter: Target folder/tag for the chosen action
  572. - assign_title_from: 1=Subject, 2=Attachment filename, 3=Do not assign
  573. - assign_tags / assign_correspondent / assign_document_type: Metadata to apply
  574. - assign_correspondent_from: 1=None, 2=Mail address, 3=Sender name, 4=Use assign_correspondent
  575. - attachment_type: 1=Attachments only, 2=All files incl. inline
  576. - consumption_scope: 1=Attachments only, 2=Full mail as .eml, 3=Both
  577. - pdf_layout: 0=System default, 1=Text+HTML, 2=HTML+text, 3=HTML only, 4=Text only
  578. ```typescript
  579. create_mail_rule({
  580. name: "Invoices",
  581. account: 1,
  582. folder: "INBOX",
  583. filter_subject: "invoice",
  584. action: 3,
  585. attachment_type: 1
  586. })
  587. ```
  588. #### update_mail_rule
  589. Patch an existing mail rule. Only the fields you supply are changed.
  590. Parameters:
  591. - id: Mail rule ID
  592. - ...any of the `create_mail_rule` fields to update
  593. ```typescript
  594. update_mail_rule({
  595. id: 1,
  596. enabled: false
  597. })
  598. ```
  599. #### delete_mail_rule
  600. Delete a mail rule. Requires an explicit confirmation flag. This changes future
  601. mail ingestion behavior but does not delete any existing documents.
  602. Parameters:
  603. - id: Mail rule ID
  604. - confirm: Must be `true` to confirm deletion
  605. ```typescript
  606. delete_mail_rule({
  607. id: 1,
  608. confirm: true
  609. })
  610. ```
  611. ## Error Handling
  612. The server will show clear error messages if:
  613. - The Paperless-NGX URL or API token is incorrect
  614. - The Paperless-NGX server is unreachable
  615. - The requested operation fails
  616. - The provided parameters are invalid
  617. ## Testing
  618. ### Unit tests
  619. Run the unit test suite (no external dependencies required):
  620. ```bash
  621. npm test
  622. ```
  623. ### E2E tests
  624. 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.
  625. **Prerequisites:** Docker, Docker Compose, and `jq`.
  626. ```bash
  627. # 1. Build the MCP server
  628. npm run build
  629. # 2. Start Paperless-ngx
  630. docker compose -f docker-compose.e2e.yml up -d
  631. # 3. Wait for Paperless to be ready, then get a token
  632. TOKEN=$(curl -s -X POST http://localhost:8000/api/token/ \
  633. -H 'Content-Type: application/json' \
  634. -d '{"username":"admin","password":"admin123"}' | jq -r '.token')
  635. # 4. Start the MCP server
  636. node build/index.js --http --port 3001 \
  637. --baseUrl http://localhost:8000 --token "$TOKEN" &
  638. MCP_PID=$!
  639. # 5. Run the E2E tests
  640. MCP_URL=http://localhost:3001/mcp \
  641. PAPERLESS_URL=http://localhost:8000 \
  642. PAPERLESS_TOKEN="$TOKEN" \
  643. npm run test:e2e
  644. # 6. Cleanup
  645. kill "$MCP_PID"
  646. docker compose -f docker-compose.e2e.yml down -v
  647. ```
  648. 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.
  649. ## Development
  650. Want to contribute or modify the server? Here's what you need to know:
  651. 1. Clone the repository
  652. 2. Install dependencies:
  653. ```bash
  654. npm install
  655. ```
  656. 3. Make your changes to server.js
  657. 4. Test locally:
  658. ```bash
  659. node server.js http://localhost:8000 your-test-token
  660. ```
  661. The server is built with:
  662. - [litemcp](https://github.com/wong2/litemcp): A TypeScript framework for building MCP servers
  663. - [zod](https://github.com/colinhacks/zod): TypeScript-first schema validation
  664. ## API Documentation
  665. 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/).
  666. ## Running the MCP Server
  667. The MCP server can be run in two modes:
  668. ### 1. stdio (default)
  669. This is the default mode. The server communicates over stdio, suitable for CLI and direct integrations.
  670. ```
  671. npm run start -- <baseUrl> <token>
  672. ```
  673. ### 2. HTTP (Streamable HTTP Transport)
  674. 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).
  675. ```
  676. npm run start -- <baseUrl> <token> --http --port 3000
  677. ```
  678. - The MCP API will be available at `POST /mcp` on the specified port.
  679. - Each request is handled statelessly, following the [StreamableHTTPServerTransport](https://github.com/modelcontextprotocol/typescript-sdk) pattern.
  680. - GET and DELETE requests to `/mcp` will return 405 Method Not Allowed.
  681. #### Per-request API token (HTTP/Docker mode)
  682. In HTTP mode, clients authenticate by supplying a Paperless-NGX API token via the standard `Authorization` header:
  683. ```
  684. Authorization: Bearer <paperless-ngx-api-token>
  685. ```
  686. 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.
  687. > **⚠️ Breaking change in v2.0.0 — HTTP mode is now authenticated by default.**
  688. >
  689. > 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`.
  690. | Scenario | `--no-auth` off (default) | `--no-auth` on |
  691. |---|---|---|
  692. | Client sends `Authorization: Bearer <tok>` | `<tok>` (client-supplied) | `<tok>` (client-supplied) |
  693. | No header, `PAPERLESS_API_KEY` / `--token` set | `401 Unauthorized` | server token |
  694. | No header, no server token | `401 Unauthorized` | `401 Unauthorized` |
  695. **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:
  696. 1. **Recommended:** have each client send `Authorization: Bearer <paperless-token>`.
  697. 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.
  698. <details>
  699. <summary>Docker Deployment</summary>
  700. 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.
  701. ### Docker Compose Configuration
  702. Create a `docker-compose.yml` file:
  703. ```yaml
  704. services:
  705. paperless-mcp:
  706. container_name: paperless-mcp
  707. image: ghcr.io/baruchiro/paperless-mcp:latest
  708. environment:
  709. - PAPERLESS_URL=http://your-paperless-ngx-server:8000
  710. - PAPERLESS_API_KEY=your-paperless-api-key
  711. - PAPERLESS_PUBLIC_URL=https://paperless-ngx.yourpublicurl.com
  712. ports:
  713. - "3000:3000"
  714. restart: unless-stopped
  715. ```
  716. Then run:
  717. ```bash
  718. docker-compose up -d
  719. ```
  720. ### Using with Continue VS Code Extension
  721. If you're using the [Continue VS Code extension](https://continue.dev/), you can configure it to use the Dockerized MCP server via SSE.
  722. Create or edit `.continue/mcpServers/paperless-mcp.yaml` at your workspace root:
  723. ```yaml
  724. name: Paperless
  725. version: 0.0.1
  726. schema: v1
  727. mcpServers:
  728. - name: Paperless
  729. type: sse
  730. url: http://localhost:3000/sse
  731. ```
  732. **Notes:**
  733. - Replace `localhost` with your Docker host's IP address or hostname if running on a remote server
  734. - The Docker container handles authentication via environment variables, so no credentials are needed in the Continue config
  735. - The SSE endpoint is available at `/sse` on the configured port (default: 3000)
  736. </details>
  737. # Credits
  738. 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.
  739. ## Debugging
  740. To debug the MCP server in VS Code, use the following launch configuration:
  741. ```json
  742. {
  743. "type": "node",
  744. "request": "launch",
  745. "name": "Debug Paperless MCP (HTTP, ts-node ESM)",
  746. "program": "${workspaceFolder}/node_modules/ts-node/dist/bin.js",
  747. "args": [
  748. "--esm",
  749. "src/index.ts",
  750. "--http",
  751. "--baseUrl",
  752. "http://your-paperless-instance:8000",
  753. "--token",
  754. "your-api-token",
  755. "--port",
  756. "3002"
  757. ],
  758. "env": {
  759. "NODE_OPTIONS": "--loader ts-node/esm",
  760. },
  761. "console": "integratedTerminal",
  762. "skipFiles": [
  763. "<node_internals>/**"
  764. ]
  765. }
  766. ```
  767. **Important:** Before debugging, uncomment the following line in `src/index.ts` (around line 175):
  768. ```typescript
  769. // await new Promise((resolve) => setTimeout(resolve, 1000000));
  770. ```
  771. This prevents the server from exiting immediately and allows you to set breakpoints and debug the code.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.