Paperless-MCP Setup

MCP (Model Context Protocol) server configuration for Paperless-NGX integration with Claude Code.

Overview

This project provides a configured instance of the @baruchiro/paperless-mcp server, which allows Claude Code to interact with your Paperless-NGX document management system.

Features

• Search and retrieve documents from Paperless-NGX
• Manage tags, correspondents, and document types
• Upload new documents
• Perform bulk operations on documents
• Full integration with Claude Code

Prerequisites

• Node.js (v16 or higher)
• A running Paperless-NGX instance
• Paperless-NGX API token

Installation

1. Clone this repository:

git clone https://github.com/Makerflix/paperless-mcp.git
cd paperless-mcp

2. Install dependencies:

npm install

3. Create your configuration file:

cp config.example.json config.json

4. Edit config.json with your Paperless-NGX details:

{
  "paperless_url": "http://your-paperless-instance:8001",
  "paperless_token": "your-api-token-here"
}

Getting Your Paperless 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
5. Copy the token to your config.json

Usage

With Claude Code

Add this to your Claude Code MCP configuration:

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["-y", "@baruchiro/paperless-mcp@latest"],
      "env": {
        "PAPERLESS_URL": "http://your-paperless-instance:8001",
        "PAPERLESS_API_KEY": "your-api-token"
      }
    }
  }
}

Standalone

Run the MCP server directly:

npx @baruchiro/paperless-mcp

Available Operations

Once configured, you can ask Claude to:

• "Show me all documents tagged as 'Invoice'"
• "Search for documents containing 'tax return'"
• "Create a new tag called 'Receipts'"
• "Download document #123"
• "List all correspondents"
• "Upload this document to Paperless"

Security

• Never commit config.json - It contains your API token
• The .gitignore file is configured to exclude sensitive files
• Use config.example.json as a template

Project Structure

paperless-mcp/
├── config.json           # Your configuration (not in git)
├── config.example.json   # Template configuration
├── package.json          # Dependencies
├── package-lock.json     # Locked dependencies
└── README.md            # This file

Troubleshooting

Connection Issues

• Verify your Paperless-NGX instance is running
• Check that the URL in config.json is correct
• Ensure your API token is valid

MCP Not Working

• Restart Claude Code after configuration changes
• Check the Claude Code logs for errors
• Verify the MCP server is properly installed

Related Projects

• Paperless-NGX - Document management system
• @baruchiro/paperless-mcp - Original MCP server package

License

ISC

Author

Makerflix