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
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/nloui--paperless-mcp"><img src="/api/listings/nloui--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

1. Install the MCP server:

npm install -g paperless-mcp

2. Add it to your Claude's MCP configuration:

For VSCode extension, edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
    }
  }
}

For Claude desktop app, edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
    }
  }
}

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

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

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 · 349 lines

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

  1. # Paperless-NGX MCP Server
  2. 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.
  3. ## Quick Start
  4. ### Installation
  5. 1. Install the MCP server:
  6. ```bash
  7. npm install -g paperless-mcp
  8. ```
  9. 2. Add it to your Claude's MCP configuration:
  10. For VSCode extension, edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:
  11. ```json
  12. {
  13. "mcpServers": {
  14. "paperless": {
  15. "command": "npx",
  16. "args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
  17. }
  18. }
  19. }
  20. ```
  21. For Claude desktop app, edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
  22. ```json
  23. {
  24. "mcpServers": {
  25. "paperless": {
  26. "command": "npx",
  27. "args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
  28. }
  29. }
  30. }
  31. ```
  32. 3. Get your API token:
  33. 1. Log into your Paperless-NGX instance
  34. 2. Click your username in the top right
  35. 3. Select "My Profile"
  36. 4. Click the circular arrow button to generate a new token
  37. 4. Replace the placeholders in your MCP config:
  38. - `http://your-paperless-instance:8000` with your Paperless-NGX URL
  39. - `your-api-token` with the token you just generated
  40. That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.
  41. ## Example Usage
  42. Here are some things you can ask Claude to do:
  43. - "Show me all documents tagged as 'Invoice'"
  44. - "Search for documents containing 'tax return'"
  45. - "Create a new tag called 'Receipts' with color #FF0000"
  46. - "Download document #123"
  47. - "List all correspondents"
  48. - "Create a new document type called 'Bank Statement'"
  49. ## Available Tools
  50. ### Document Operations
  51. #### list_documents
  52. Get a paginated list of all documents.
  53. Parameters:
  54. - page (optional): Page number
  55. - page_size (optional): Number of documents per page
  56. ```typescript
  57. list_documents({
  58. page: 1,
  59. page_size: 25
  60. })
  61. ```
  62. #### get_document
  63. Get a specific document by ID.
  64. Parameters:
  65. - id: Document ID
  66. ```typescript
  67. get_document({
  68. id: 123
  69. })
  70. ```
  71. #### search_documents
  72. Full-text search across documents.
  73. Parameters:
  74. - query: Search query string
  75. ```typescript
  76. search_documents({
  77. query: "invoice 2024"
  78. })
  79. ```
  80. #### download_document
  81. Download a document file by ID.
  82. Parameters:
  83. - id: Document ID
  84. - original (optional): If true, downloads original file instead of archived version
  85. ```typescript
  86. download_document({
  87. id: 123,
  88. original: false
  89. })
  90. ```
  91. #### bulk_edit_documents
  92. Perform bulk operations on multiple documents.
  93. Parameters:
  94. - documents: Array of document IDs
  95. - method: One of:
  96. - set_correspondent: Set correspondent for documents
  97. - set_document_type: Set document type for documents
  98. - set_storage_path: Set storage path for documents
  99. - add_tag: Add a tag to documents
  100. - remove_tag: Remove a tag from documents
  101. - modify_tags: Add and/or remove multiple tags
  102. - delete: Delete documents
  103. - reprocess: Reprocess documents
  104. - set_permissions: Set document permissions
  105. - merge: Merge multiple documents
  106. - split: Split a document into multiple documents
  107. - rotate: Rotate document pages
  108. - delete_pages: Delete specific pages from a document
  109. - Additional parameters based on method:
  110. - correspondent: ID for set_correspondent
  111. - document_type: ID for set_document_type
  112. - storage_path: ID for set_storage_path
  113. - tag: ID for add_tag/remove_tag
  114. - add_tags: Array of tag IDs for modify_tags
  115. - remove_tags: Array of tag IDs for modify_tags
  116. - permissions: Object for set_permissions with owner, permissions, merge flag
  117. - metadata_document_id: ID for merge to specify metadata source
  118. - delete_originals: Boolean for merge/split
  119. - pages: String for split "[1,2-3,4,5-7]" or delete_pages "[2,3,4]"
  120. - degrees: Number for rotate (90, 180, or 270)
  121. Examples:
  122. ```typescript
  123. // Add a tag to multiple documents
  124. bulk_edit_documents({
  125. documents: [1, 2, 3],
  126. method: "add_tag",
  127. tag: 5
  128. })
  129. // Set correspondent and document type
  130. bulk_edit_documents({
  131. documents: [4, 5],
  132. method: "set_correspondent",
  133. correspondent: 2
  134. })
  135. // Merge documents
  136. bulk_edit_documents({
  137. documents: [6, 7, 8],
  138. method: "merge",
  139. metadata_document_id: 6,
  140. delete_originals: true
  141. })
  142. // Split document into parts
  143. bulk_edit_documents({
  144. documents: [9],
  145. method: "split",
  146. pages: "[1-2,3-4,5]"
  147. })
  148. // Modify multiple tags at once
  149. bulk_edit_documents({
  150. documents: [10, 11],
  151. method: "modify_tags",
  152. add_tags: [1, 2],
  153. remove_tags: [3, 4]
  154. })
  155. ```
  156. #### post_document
  157. Upload a new document to Paperless-NGX.
  158. Parameters:
  159. - file: Base64 encoded file content
  160. - filename: Name of the file
  161. - title (optional): Title for the document
  162. - created (optional): DateTime when the document was created (e.g. "2024-01-19" or "2024-01-19 06:15:00+02:00")
  163. - correspondent (optional): ID of a correspondent
  164. - document_type (optional): ID of a document type
  165. - storage_path (optional): ID of a storage path
  166. - tags (optional): Array of tag IDs
  167. - archive_serial_number (optional): Archive serial number
  168. - custom_fields (optional): Array of custom field IDs
  169. ```typescript
  170. post_document({
  171. file: "base64_encoded_content",
  172. filename: "invoice.pdf",
  173. title: "January Invoice",
  174. created: "2024-01-19",
  175. correspondent: 1,
  176. document_type: 2,
  177. tags: [1, 3],
  178. archive_serial_number: "2024-001"
  179. })
  180. ```
  181. ### Tag Operations
  182. #### list_tags
  183. Get all tags.
  184. ```typescript
  185. list_tags()
  186. ```
  187. #### create_tag
  188. Create a new tag.
  189. Parameters:
  190. - name: Tag name
  191. - color (optional): Hex color code (e.g. "#ff0000")
  192. - match (optional): Text pattern to match
  193. - matching_algorithm (optional): One of "any", "all", "exact", "regular expression", "fuzzy"
  194. ```typescript
  195. create_tag({
  196. name: "Invoice",
  197. color: "#ff0000",
  198. match: "invoice",
  199. matching_algorithm: "fuzzy"
  200. })
  201. ```
  202. ### Correspondent Operations
  203. #### list_correspondents
  204. Get all correspondents.
  205. ```typescript
  206. list_correspondents()
  207. ```
  208. #### create_correspondent
  209. Create a new correspondent.
  210. Parameters:
  211. - name: Correspondent name
  212. - match (optional): Text pattern to match
  213. - matching_algorithm (optional): One of "any", "all", "exact", "regular expression", "fuzzy"
  214. ```typescript
  215. create_correspondent({
  216. name: "ACME Corp",
  217. match: "ACME",
  218. matching_algorithm: "fuzzy"
  219. })
  220. ```
  221. ### Document Type Operations
  222. #### list_document_types
  223. Get all document types.
  224. ```typescript
  225. list_document_types()
  226. ```
  227. #### create_document_type
  228. Create a new document type.
  229. Parameters:
  230. - name: Document type name
  231. - match (optional): Text pattern to match
  232. - matching_algorithm (optional): One of "any", "all", "exact", "regular expression", "fuzzy"
  233. ```typescript
  234. create_document_type({
  235. name: "Invoice",
  236. match: "invoice total amount due",
  237. matching_algorithm: "any"
  238. })
  239. ```
  240. ## Error Handling
  241. The server will show clear error messages if:
  242. - The Paperless-NGX URL or API token is incorrect
  243. - The Paperless-NGX server is unreachable
  244. - The requested operation fails
  245. - The provided parameters are invalid
  246. ## Development
  247. Want to contribute or modify the server? Here's what you need to know:
  248. 1. Clone the repository
  249. 2. Install dependencies:
  250. ```bash
  251. npm install
  252. ```
  253. 3. Make your changes to server.js
  254. 4. Test locally:
  255. ```bash
  256. node server.js http://localhost:8000 your-test-token
  257. ```
  258. The server is built with:
  259. - [litemcp](https://github.com/wong2/litemcp): A TypeScript framework for building MCP servers
  260. - [zod](https://github.com/colinhacks/zod): TypeScript-first schema validation
  261. ## API Documentation
  262. 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/).
  263. ## Running the MCP Server
  264. The MCP server can be run in two modes:
  265. ### 1. stdio (default)
  266. This is the default mode. The server communicates over stdio, suitable for CLI and direct integrations.
  267. ```
  268. npm run start -- <baseUrl> <token>
  269. ```
  270. ### 2. HTTP (Streamable HTTP Transport)
  271. 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).
  272. ```
  273. npm run start -- <baseUrl> <token> --http --port 3000
  274. ```
  275. - The MCP API will be available at `POST /mcp` on the specified port.
  276. - Each request is handled statelessly, following the [StreamableHTTPServerTransport](https://github.com/modelcontextprotocol/typescript-sdk) pattern.
  277. - GET and DELETE requests to `/mcp` will return 405 Method Not Allowed.

Ratings and comments

Sign in to rate this skill.

Sign in

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