Paperless Ngx

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)

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)

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

Share Links (4 tools)

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

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