<!-- -->

Paperless-NGX MCP Server

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.

Quick Start

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 | 5 | Paperless-ngx REST API version. Use 10 for Paperless-ngx v3+. If you see HTTP 406 errors, set this to 10. |
| 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'"

Available Tools

Document Operations

list_documents

Get a paginated list of all documents.

Parameters:
- page (optional): Page number
- page_size (optional): Number of documents per page

list_documents({
  page: 1,
  page_size: 25
})

get_document

Get a specific document by ID.

Parameters:
- id: Document ID

get_document({
  id: 123
})

search_documents

Full-text search across documents.

Parameters:
- query: Search query string

search_documents({
  query: "invoice 2024"
})

download_document

Download a document file by ID.

Parameters:
- id: Document ID
- original (optional): If true, downloads original file instead of archived version

download_document({
  id: 123,
  original: false
})

get_document_thumbnail

Get a document thumbnail (image preview) by ID. Returns the thumbnail as a base64-encoded WebP image resource.

Parameters:
- id: Document ID

get_document_thumbnail({
  id: 123
})

bulk_edit_documents

Perform bulk operations on multiple documents.

Parameters:
- documents: Array of document IDs
- method: One of:
- set_correspondent: Set correspondent for documents
- set_document_type: Set document type for documents
- set_storage_path: Set storage path for documents
- add_tag: Add a tag to documents
- remove_tag: Remove a tag from documents
- modify_tags: Add and/or remove multiple tags
- delete: Delete documents
- reprocess: Reprocess documents
- set_permissions: Set document permissions
- merge: Merge multiple documents
- split: Split a document into multiple documents
- rotate: Rotate document pages
- delete_pages: Delete specific pages from a document
- Additional parameters based on method:
- correspondent: ID for set_correspondent
- document_type: ID for set_document_type
- storage_path: ID for set_storage_path
- tag: ID for add_tag/remove_tag
- add_tags: Array of tag IDs for modify_tags
- remove_tags: Array of tag IDs for modify_tags
- permissions: Object for set_permissions with owner, permissions, merge flag
- metadata_document_id: ID for merge to specify metadata source
- delete_originals: Boolean for merge/split
- pages: String for split "[1,2-3,4,5-7]" or delete_pages "[2,3,4]"
- degrees: Number for rotate (90, 180, or 270)

Examples:

// Add a tag to multiple documents

bulk_edit_documents({

  documents: [1, 2, 3],

  method: "add_tag",

  tag: 5

})

// Set correspondent and document type

bulk_edit_documents({

  documents: [4, 5],

  method: "set_correspondent",

  correspondent: 2

})
// Merge documents

bulk_edit_documents({

  documents: [6, 7, 8],

  method: "merge",

  metadata_document_id: 6,

  delete_originals: true

})
// Split document into parts

bulk_edit_documents({

  documents: [9],

  method: "split",

  pages: "[1-2,3-4,5]"

})
// Modify multiple tags at once

bulk_edit_documents({

  documents: [10, 11],

  method: "modify_tags",

  add_tags: [1, 2],

  remove_tags: [3, 4]

})
// Modify custom fields

bulk_edit_documents({

  documents: [12, 13],

  method: "modify_custom_fields",

  add_custom_fields: [

    { field: 2, value: "year" }

  ],

  remove_custom_fields: []

})
// Set an empty custom field value, e.g. a date field used as a pending marker

bulk_edit_documents({

  documents: [14],

  method: "modify_custom_fields",

  add_custom_fields: [

    { field: 9, value: "" }

  ],

  remove_custom_fields: []

})

post_document

Upload a new document to Paperless-NGX.

Two upload modes:

1. Base64 mode (traditional): Provide file (base64-encoded content) + filename
2. Filesystem mode (efficient): Provide file_path (absolute path on server)

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.

…