# paperless-mcp

MCP server exposing Paperless-ngx document management via its REST API.

## Overview

A Model Context Protocol (MCP) server that wraps the [Paperless-ngx](https://docs.paperless-ngx.com/) REST API, enabling Claude and other AI models to:

- Search and retrieve documents
- Get full document content and metadata
- Update document metadata (title, correspondent, document type, tags)
- List available tags, correspondents, and document types
- Check Paperless-ngx system status

## Installation

```bash
npm install
```

## Configuration

Set these environment variables before starting:

- `PAPERLESS_URL` — required, e.g. `http://paperless.local:8000`
- `PAPERLESS_TOKEN` — required, API token from Paperless-ngx (obtained via `/api/token/`)
- `PAPERLESS_TIMEOUT_MS` — optional, default `15000` ms

### Obtaining a Paperless-ngx API token

```bash
# Login to Paperless-ngx and go to Settings > Profile > REST API Tokens
# Or obtain programmatically:
curl -X POST http://paperless.local:8000/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"your-user","password":"your-pass"}'
```

## Running

```bash
# Start the MCP server (reads from stdin, writes to stdout)
PAPERLESS_URL="http://paperless.local:8000" \
PAPERLESS_TOKEN="your-token" \
node dist/index.js
```

Or use the bin alias:

```bash
npm run build
PAPERLESS_URL="..." PAPERLESS_TOKEN="..." \
  ./node_modules/.bin/paperless-mcp
```

## Development

```bash
npm run dev        # Watch mode with tsx
npm run build      # Compile TypeScript
npm run typecheck  # Type-check without emitting
npm run lint       # ESLint (mikey-pro)
npm run format     # Prettier
npm test           # Vitest
```

All checks must pass before committing:

```bash
npm run typecheck && npm run lint && npm test && npm run build
```

## API Tools

The MCP server registers 8 tools:

1. **paperless_health** — System status (database, task count)
2. **search_documents** — Full-text search with pagination
3. **get_document** — Fetch full document (including content)
4. **update_document** — Update title, correspondent, type, tags
5. **list_tags** — All available tags
6. **list_correspondents** — All available correspondents
7. **list_document_types** — All available document types

## Architecture

```text
src/
  index.ts           — Entrypoint, stdio server setup
  server.ts          — Tool registration (8 tools)
  paperless.ts       — Paperless-ngx API client + types
  paperless.test.ts  — Comprehensive test suite (26 tests)
```

## CI/CD

- **`.gitea/workflows/ci.yml`** — Gitea Actions: lint, typecheck, test, build
- **`.gitea/workflows/mirror.yml`** — Auto-mirror to GitHub on every push

## License

MIT