Paperless-NGX MCP server

This MCP server provides integration between Claude AI and your Paperless-NGX document management system, allowing you to search, create, and manage documents, tags, correspondents, and document types through natural language commands.

Installation

Quick Installation via Smithery

The easiest way to install the Paperless-NGX MCP server is with Smithery:

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

Manual Installation

1. Install the MCP server package:

npm install -g paperless-mcp

2. Add the server 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"]
    }
  }
}

Getting 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

Replace the placeholders in your MCP config with your actual Paperless-NGX URL and API token.

Using the MCP Server

Once configured, you can ask Claude to help manage your Paperless-NGX documents using natural language. Here are some example prompts:

• "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 Management

Listing and Searching Documents

To list all documents (paginated):

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

To get a specific document by ID:

get_document({
  id: 123
})

To search documents:

search_documents({
  query: "invoice 2024"
})

Downloading Documents

To download a document file:

download_document({
  id: 123,
  original: false  // set to true for the original file instead of archived version
})

Uploading Documents

To add a new document:

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

Bulk Editing Documents

The system supports powerful bulk operations on multiple documents:

// Add a tag to multiple documents
bulk_edit_documents({
  documents: [1, 2, 3],
  method: "add_tag",
  tag: 5
})

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

Tag Management

To list all tags:

list_tags()

To create a new tag:

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

Correspondent Management

To list all correspondents:

list_correspondents()

To create a new correspondent:

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

Document Type Management

To list all document types:

list_document_types()

To create a new document type:

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

Troubleshooting

If you encounter issues, check that:

• Your Paperless-NGX URL is correct and accessible
• Your API token is valid and correctly entered
• Your Paperless-NGX server is running and responding

The server will provide error messages if there are problems with connectivity, authentication, or parameter validation.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.