📌Overview

Purpose: To provide an MCP (Model Context Protocol) server for seamless interaction with a Paperless-NGX API server, allowing users to manage their documents effectively.

Overview: The Paperless-NGX MCP Server offers a set of tools designed to manage various elements such as documents, tags, correspondents, and document types within a Paperless-NGX instance. This server acts as a bridge for users to easily perform operations through commands while integrating with Claude Desktop.

Key Features:

Document Management: Provides functionalities for CRUD operations (Create, Read, Update, Delete) on documents, including bulk edits, downloads, and full-text searches.
Tag and Correspondent Operations: Allows users to create, list, and manage tags and correspondents, ensuring better categorization and retrieval of documents.
Error Handling: Equipped with clear error messages and validation for inputs, ensuring a smooth user experience.
Development Friendly: Built with TypeScript using frameworks that facilitate easy modifications and contributions.

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:

npx -y @smithery/cli install @nloui/paperless-mcp --client claude

Manual Installation

Install the MCP server:

npm install -g paperless-mcp

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"]
    }
  }
}

Get your API token:
- Log into your Paperless-NGX instance
- Click your username in the top right
- Select "My Profile"
- Click the circular arrow button to generate a new token
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

Now you can ask Claude to help you manage your Paperless-NGX documents.

Example Usage

You can ask Claude to do tasks such as:

Show all documents tagged as "Invoice"
Search for documents containing "tax return"
Create a new tag called "Receipts" with color #FF0000
Download a document by ID
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
})

bulk_edit_documents

Perform bulk operations on multiple documents.

Parameters:

documents: Array of document IDs
method: One of:
- set_correspondent
- set_document_type
- set_storage_path
- add_tag
- remove_tag
- modify_tags
- delete
- reprocess
- set_permissions
- merge
- split
- rotate
- delete_pages
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 or delete_pages (e.g., "[1,2-3,4,5-7]")
- 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]
})

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

post_document({
  file: "base64_encoded_content",
  filename: "invoice.pdf",
  title: "January Invoice",
  created: "2024-01-19",
  correspondent: 1,
  document_type: 2,
  tags: [1, 3],
  archive_serial_number: "2024-001"
})

Tag Operations

list_tags

Get all tags.

list_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"

create_tag({
  name: "Invoice",
  color: "#ff0000",
  match: "invoice",
  matching_algorithm: "fuzzy"
})

Correspondent Operations

list_correspondents

Get all correspondents.

list_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"

create_correspondent({
  name: "ACME Corp",
  match: "ACME",
  matching_algorithm: "fuzzy"
})

Document Type Operations

list_document_types

Get all document types.

list_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"

create_document_type({
  name: "Invoice",
  match: "invoice total amount due",
  matching_algorithm: "any"
})

Error Handling

The server shows clear error messages for:

Incorrect Paperless-NGX URL or API token
Unreachable Paperless-NGX server
Failed operations
Invalid parameters

Development

To contribute or modify the server:

Clone the repository
Install dependencies:

npm install

Make changes to server.js
Test locally:

node server.js http://localhost:8000 your-test-token

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:
https://docs.paperless-ngx.com/api/