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

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)

Clone the repository:

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

Configure environment variables (see Configuration)
Start the server:
```
npm run server
```
Open http://localhost:8081 to access the web UI
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)

Tool	Description
`list_documents`	List all documents with filtering and pagination
`get_document`	Get document details by ID
`search_documents`	Full-text search across documents
`list_documents_by_tag`	List documents with a specific tag
`download_document`	Download document file
`post_document`	Upload a new document
`update_document`	Update document metadata
`delete_document`	Delete a document
`get_document_suggestions`	Get AI suggestions for tags/correspondent
`get_document_metadata`	Get file metadata (checksum, size)
`get_document_notes`	Get notes on a document
`add_document_note`	Add a note to a document
`get_document_history`	Get audit history
`bulk_edit_documents`	Bulk operations on multiple documents

Tags (5 tools)

Tool	Description
`list_tags`	List all tags
`get_tag`	Get tag by ID
`create_tag`	Create a new tag
`update_tag`	Update a tag
`delete_tag`	Delete a tag

Correspondents (5 tools)

Tool	Description
`list_correspondents`	List all correspondents
`get_correspondent`	Get correspondent by ID
`create_correspondent`	Create a new correspondent
`update_correspondent`	Update a correspondent
`delete_correspondent`	Delete a correspondent

Document Types (5 tools)

Tool	Description
`list_document_types`	List all document types
`get_document_type`	Get document type by ID
`create_document_type`	Create a new document type
`update_document_type`	Update a document type
`delete_document_type`	Delete a document type

Storage Paths (5 tools)

Tool	Description
`list_storage_paths`	List all storage paths
`get_storage_path`	Get storage path by ID
`create_storage_path`	Create a new storage path
`update_storage_path`	Update a storage path
`delete_storage_path`	Delete a storage path

Custom Fields (5 tools)

Tool	Description
`list_custom_fields`	List all custom fields
`get_custom_field`	Get custom field by ID
`create_custom_field`	Create a new custom field
`update_custom_field`	Update a custom field
`delete_custom_field`	Delete a custom field

Saved Views (5 tools)

Tool	Description
`list_saved_views`	List all saved views
`get_saved_view`	Get saved view by ID
`create_saved_view`	Create a new saved view
`update_saved_view`	Update a saved view
`delete_saved_view`	Delete a saved view

Tool	Description
`list_share_links`	List all share links
`get_share_link`	Get share link by ID
`create_share_link`	Create a shareable link
`delete_share_link`	Revoke a share link

System (2 tools)

Tool	Description
`get_status`	Get server status
`get_statistics`	Get document statistics

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

Go to Google Cloud Console
Create a new project (or select existing)
Create OAuth 2.0 credentials (Web application)
Add authorized redirect URI: https://your-mcp-server.com/callback
Copy Client ID and Client Secret to your .env file
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