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 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

Related MCP server: KnowledgeMCP

Installation

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

# 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

# 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:

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

Development

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:

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

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