# Paperless-NGX MCP Server

A comprehensive Model Context Protocol (MCP) server for [Paperless-NGX](https://docs.paperless-ngx.com/) 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

```bash
npm install paperless-ngx-mcp
```

Or install globally:

```bash
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):

```json
{
  "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:
   ```bash
   git clone https://github.com/your-username/paperless-ngx-mcp.git
   cd paperless-ngx-mcp
   npm install
   ```

2. Configure environment variables (see [Configuration](#configuration))

3. Start the server:
   ```bash
   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:

```bash
# 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](https://console.cloud.google.com/apis/credentials)
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

```bash
# 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](LICENSE) file.

## Acknowledgments

- [Paperless-NGX](https://docs.paperless-ngx.com/) - The excellent document management system
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol enabling AI tool use
- [LiteMCP](https://github.com/wong2/litemcp) - Lightweight MCP server framework