# Paperless-ngx MCP Server

A Model Context Protocol (MCP) server that connects AI assistants (such as Claude Desktop, Cursor, and other MCP clients) to a [Paperless-ngx](https://docs.paperless-ngx.com/) document archive.

## Features

- **Full-Text & Metadata Search**: Search through documents using OCR text, tags, correspondents, document types, and date ranges.
- **OCR Content Inspection**: Read full OCR text, metadata, and custom notes for any document.
- **Document Download**: Save original or archived PDF versions to local storage.
- **Metadata Management**: View reference collections (tags, correspondents, document types) and update document properties.
- **Document Upload**: Upload local files into Paperless with automatic background OCR processing.
- **Archive Statistics**: Retrieve instant counts of documents, tags, correspondents, and types.

---

## Tools Reference

| Tool | Parameters | Description |
|---|---|---|
| `search_documents` | `query`, `tags`, `correspondent`, `document_type`, `created_after`, `created_before`, `limit` | Search documents with filters and text query |
| `get_document` | `document_id`, `include_content` | Get document metadata and OCR content |
| `download_document` | `document_id`, `original`, `save_as` | Download original file or archive PDF to disk |
| `list_tags` | — | List all tags with item counts |
| `list_correspondents` | — | List all correspondents with item counts |
| `list_document_types` | — | List all document types with item counts |
| `stats` | — | Summary of counts across the archive |
| `update_document` | `document_id`, `title`, `correspondent`, `document_type`, `add_tags`, `remove_tags`, `create_missing` | Update metadata and assign/remove tags |
| `upload_document` | `file_path`, `title`, `correspondent`, `document_type`, `tags`, `created`, `create_missing` | Upload a new file with metadata |

---

## Configuration

The server requires the following environment variables:

| Variable | Description | Example |
|---|---|---|
| `PAPERLESS_URL` | Base URL of the Paperless-ngx instance | `http://localhost:8000` |
| `PAPERLESS_TOKEN` | Paperless API authentication token | `your_api_token_here` |
| `PAPERLESS_DOWNLOAD_DIR` | (Optional) Path where downloaded documents will be saved | `~/Downloads` |

---

## Installation & Setup

For detailed installation instructions, see [SETUP.md](SETUP.md).

### Quick Start (Claude Desktop Config)

Add the server to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "paperless": {
      "command": "python",
      "args": ["/path/to/src/server.py"],
      "env": {
        "PAPERLESS_URL": "http://localhost:8000",
        "PAPERLESS_TOKEN": "your_api_token_here",
        "PAPERLESS_DOWNLOAD_DIR": "/path/to/downloads"
      }
    }
  }
}
```

Or run via `uv`:

```json
{
  "mcpServers": {
    "paperless": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-paperless", "src/server.py"],
      "env": {
        "PAPERLESS_URL": "http://localhost:8000",
        "PAPERLESS_TOKEN": "your_api_token_here",
        "PAPERLESS_DOWNLOAD_DIR": "/path/to/downloads"
      }
    }
  }
}
```

---

## Helper Script

A PowerShell helper script `paperless-api.ps1` is provided for quick CLI interaction and testing:

```powershell
# Get archive summary
.\paperless-api.ps1 -Token "your_token"

# Query documents
.\paperless-api.ps1 -Token "your_token" -Endpoint "documents/?page_size=5"

# Export all tags to JSON
.\paperless-api.ps1 -Token "your_token" -Endpoint "tags/" -All -OutFile tags.json
```

---

## Packaging as MCP Bundle (.mcpb)

To build the desktop bundle:

```powershell
Compress-Archive -Path manifest.json,pyproject.toml,src -DestinationPath paperless-ngx.zip -Force
Move-Item paperless-ngx.zip paperless-ngx.mcpb -Force
```

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.