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

1. Install the MCP server:

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:

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

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.

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): One of "any", "all", "exact", "regular expression", "fuzzy"

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): One of "any", "all", "exact", "regular expression", "fuzzy"

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): One of "any", "all", "exact", "regular expression", "fuzzy"

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.