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

Installing via Smithery

To install Paperless NGX MCP Server for Claude Desktop automatically via Smithery:

Manual Installation

Add these to your MCP config file:

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

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

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)

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

get_document

Get a specific document by ID.

Parameters:

• id: Document ID

search_documents

Full-text search across documents.

Parameters:

• query: Search query string

download_document

Download a document file by ID.

Parameters:

• id: Document ID

• original (optional): If true, downloads original file instead of archived version

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:

post_document

Upload a new document to Paperless-NGX.

Parameters:

• file: Base64 encoded file content

• filename: Name of the file

• title (optional): Title for the document

• created (optional): DateTime when the document was created (e.g. "2024-01-19" or "2024-01-19 06:15:00+02:00")

• correspondent (optional): ID of a correspondent

• document_type (optional): ID of a document type

• storage_path (optional): ID of a storage path

• tags (optional): Array of tag IDs

• archive_serial_number (optional): Archive serial number

• custom_fields (optional): Array of custom field IDs

Tag Operations

list_tags

Get all tags.

create_tag

Create a new tag.

Parameters:

• name: Tag name

• color (optional): Hex color code (e.g. "#ff0000")

• match (optional): Text pattern to match

• matching_algorithm (optional): Number between 0 and 6: 0 - None 1 - Any word 2 - All words 3 - Exact match 4 - Regular expression 5 - Fuzzy word 6 - Automatic

Correspondent Operations

list_correspondents

Get all correspondents.

create_correspondent

Create a new correspondent.

Parameters:

• name: Correspondent name

• match (optional): Text pattern to match

• matching_algorithm (optional): Number between 0 and 6: 0 - None 1 - Any word 2 - All words 3 - Exact match 4 - Regular expression 5 - Fuzzy word 6 - Automatic

Document Type Operations

list_document_types

Get all document types.

create_document_type

Create a new document type.

Parameters:

• name: Document type name

• match (optional): Text pattern to match

• matching_algorithm (optional): Number between 0 and 6: 0 - None 1 - Any word 2 - All words 3 - Exact match 4 - Regular expression 5 - Fuzzy word 6 - Automatic

Custom Field Operations

list_custom_fields

Get all custom fields.

get_custom_field

Get a specific custom field by ID.

Parameters:

• id: Custom field ID

create_custom_field

Create a new custom field.

Parameters:

• name: Custom field name

• data_type: One of "string", "url", "date", "boolean", "integer", "float", "monetary", "documentlink", "select"

• extra_data (optional): Extra data for the custom field, such as select options

update_custom_field

Update an existing custom field.

Parameters:

• id: Custom field ID

• name (optional): New custom field name

• data_type (optional): New data type

• extra_data (optional): Extra data for the custom field

delete_custom_field

Delete a custom field.

Parameters:

• id: Custom field ID

bulk_edit_custom_fields

Perform bulk operations on multiple custom fields.

Parameters:

• custom_fields: Array of custom field IDs

• operation: One of "delete"

Error Handling

The server will show clear error messages if:

• The Paperless-NGX URL or API token is incorrect

• The Paperless-NGX server is unreachable

• The requested operation fails

• The provided parameters are invalid

Development

Want to contribute or modify the server? Here's what you need to know:

1. Clone the repository

2. Install dependencies:

3. Make your changes to server.js

4. Test locally:

The server is built with:

• litemcp: A TypeScript framework for building MCP servers

• zod: TypeScript-first schema validation

API Documentation

This MCP server implements endpoints from the Paperless-NGX REST API. For more details about the underlying API, see the official documentation.

Running the MCP Server

The MCP server can be run in two modes:

1. stdio (default)

This is the default mode. The server communicates over stdio, suitable for CLI and direct integrations.

2. HTTP (Streamable HTTP Transport)

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 to be installed (it is included as a dependency).

• The MCP API will be available at POST /mcp on the specified port.

• Each request is handled statelessly, following the StreamableHTTPServerTransport pattern.

• GET and DELETE requests to /mcp will return 405 Method Not Allowed.

Credits

This project is a fork of nloui/paperless-mcp. Many thanks to the original author for their work. Contributions and improvements may be returned upstream.

Debugging

To debug the MCP server in VS Code, use the following launch configuration:

Important: Before debugging, uncomment the following line in src/index.ts (around line 175):

This prevents the server from exiting immediately and allows you to set breakpoints and debug the code.