Paperless-NGX MCP Server

A comprehensive Model Context Protocol (MCP) server for Paperless-NGX document management. This server enables Claude AI to interact with your Paperless-NGX instance through natural language.

Features

• 50 Tools for complete Paperless-NGX management

• Dual Mode: Works with both Claude Desktop (stdio) and Claude.ai (HTTP/OAuth)

• Web UI: Dashboard, setup wizard, and tool reference

• Full CRUD: Create, read, update, delete operations for all entities

• OAuth 2.0: Secure remote access with Google Workspace authentication

Related MCP server: Google Docs MCP Server

Quick Start

Installation

npm install paperless-ngx-mcp

Or install globally:

npm install -g paperless-ngx-mcp

Claude Desktop (Local Mode)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": [
        "paperless-ngx-mcp",
        "https://your-paperless-url.com",
        "your-api-token"
      ]
    }
  }
}

Get your API token from: Paperless-NGX > Settings > API Tokens > Add Token

Claude.ai (Remote Mode with OAuth)

1. Clone the repository:

   git clone https://github.com/your-username/paperless-ngx-mcp.git
   cd paperless-ngx-mcp
   npm install

2. Configure environment variables (see Configuration)

3. Start the server:

   npm run server

4. Open http://localhost:8081 to access the web UI

5. Add the MCP server URL to Claude.ai's remote MCP settings

Configuration

Create a .env file or set environment variables:

# Required: Paperless-NGX Connection
PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TOKEN=your-api-token

# Optional: OAuth (for remote mode with Claude.ai)
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
ALLOWED_DOMAIN=example.com  # Restrict to Google Workspace domain

# Optional: Server Settings
MCP_SERVER_URL=https://mcp.example.com  # Public URL for OAuth callbacks
JWT_SECRET=your-jwt-secret  # Auto-generated if not provided
PORT=8081

Available Tools (50 Total)

Documents (14 tools)

Tags (5 tools)

Correspondents (5 tools)

Document Types (5 tools)

Storage Paths (5 tools)

Custom Fields (5 tools)

Saved Views (5 tools)

Share Links (4 tools)

System (2 tools)

Web UI

The HTTP server includes a web interface:

• Dashboard (/) - Connection status and quick start guide

• Setup (/setup) - Configuration wizard

• Tools (/tools) - Complete tool reference with parameters

• Logs (/logs) - Server activity logs

Example Prompts

Once connected, you can ask Claude things like:

• "Search for documents about taxes from 2024"

• "List all my invoices from last month"

• "Create a new tag called 'Important' with red color"

• "What correspondents do I have?"

• "Download document 123"

• "Add a note to document 456 saying 'Review needed'"

• "Get suggestions for document 789"

• "Show me storage usage statistics"

OAuth Setup for Claude.ai

1. Go to Google Cloud Console

2. Create a new project (or select existing)

3. Create OAuth 2.0 credentials (Web application)

4. Add authorized redirect URI: https://your-mcp-server.com/callback

5. Copy Client ID and Client Secret to your .env file

6. Optionally set ALLOWED_DOMAIN to restrict access to your organization

Development

# Install dependencies
npm install

# Run in development mode (with auto-reload)
npm run dev

# Run stdio mode (for testing)
npm start https://paperless.example.com your-token

License

MIT License - see LICENSE file.

Acknowledgments

• Paperless-NGX - The excellent document management system

• Model Context Protocol - The protocol enabling AI tool use

• LiteMCP - Lightweight MCP server framework