# Paperless Agent Toolkit

MCP server for [Paperless-ngx](https://docs.paperless-ngx.com/) document management, plus reusable
agent skills built on top of it (e.g. auto-filing documents tagged `TODO`).

This repo has two parts:

- **`src/paperless_mcp/`** — an [MCP](https://modelcontextprotocol.io/) server exposing Paperless-ngx
  as tools: list/search documents, read full OCR content, update metadata, manage tags/correspondents/
  document types, find duplicates. Works with any MCP-compatible client, not just Claude.
- **`.claude/skills/`** — Claude Code skills that use those tools to carry out a workflow end-to-end
  (currently: `paperless-todo-cleanup`, which files every `TODO`-tagged document — title,
  correspondent, document type, tags — then clears the tag).

## Setup

Requires Python >=3.10.

```bash
pip install -e .
```

Set two environment variables (Paperless UI → Settings → API Tokens for the token):

```bash
export PAPERLESS_URL="http://<paperless-host>:8000"
export PAPERLESS_TOKEN="<your-api-token>"
```

Run the server directly (stdio transport):

```bash
python -m paperless_mcp.server
```

### Registering with an MCP client

For Claude Code, add it as a project-scoped MCP server (values from a `.env` or your shell, not
hardcoded) — e.g. via `claude mcp add`, or directly in `.mcp.json`:

```json
{
  "mcpServers": {
    "paperless-ngx": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "paperless_mcp.server"],
      "env": {
        "PAPERLESS_URL": "http://<paperless-host>:8000",
        "PAPERLESS_TOKEN": "<your-api-token>"
      }
    }
  }
}
```

`PAPERLESS_TOKEN` is a credential — keep it in a gitignored config (e.g. Claude Code's
`.claude/settings.local.json` or your own `.env`), never in a tracked file.

## Tools

| Tool | Purpose |
|---|---|
| `list_documents` | Search/filter documents (tag, correspondent, type, full-text query, tag count); paginates internally |
| `get_document` | Full document detail, including OCR `content` and checksum |
| `update_document` | Set title/correspondent/document_type/tags/created/content; unknown names auto-create |
| `add_tags` / `remove_tags` | Adjust a document's tags without touching the rest |
| `delete_document` | Delete a document (requires `confirm=True`) |
| `find_duplicate_documents` | Group documents by identical file checksum |
| `list_tags` / `list_correspondents` / `list_document_types` | Enumerate existing values, for reuse before creating new ones |
| `create_tag` / `create_correspondent` / `create_document_type` | Create explicitly (usually unnecessary — `update_document` auto-creates) |
| `rename_tag` / `rename_correspondent` / `rename_document_type` | Rename by current name or id |
| `delete_tag` / `delete_correspondent` / `delete_document_type` | Delete by name or id (requires `confirm=True`) |
| `get_instance_url` | Return the configured Paperless base URL, e.g. for building web UI links |

## Skills

- **`paperless-todo-cleanup`** — processes every `TODO`-tagged document: picks a descriptive title,
  sets correspondent/document type where determinable, applies 3–4 tags (reusing existing ones over
  creating new), then drops the `TODO` tag. Invoke with `/paperless-todo-cleanup` in Claude Code.