Provides tools for searching, retrieving, updating documents, and managing tags, correspondents, and document types in Paperless-ngx.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@paperless-mcp search for documents with tag 'urgent'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server exposing Paperless-ngx document management via its REST API.
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
npm installSet 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
# 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"}'# Start the MCP server (reads from stdin, writes to stdout)
PAPERLESS_URL="http://paperless.local:8000" \
PAPERLESS_TOKEN="your-token" \
node dist/index.jsOr use the bin alias:
npm run build
PAPERLESS_URL="..." PAPERLESS_TOKEN="..." \
./node_modules/.bin/paperless-mcpnpm 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 # VitestAll checks must pass before committing:
npm run typecheck && npm run lint && npm test && npm run buildThe MCP server registers 8 tools:
paperless_health — System status (database, task count)
search_documents — Full-text search with pagination
get_document — Fetch full document (including content)
update_document — Update title, correspondent, type, tags
list_tags — All available tags
list_correspondents — All available correspondents
list_document_types — All available document types
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).gitea/workflows/ci.yml — Gitea Actions: lint, typecheck, test, build
.gitea/workflows/mirror.yml — Auto-mirror to GitHub on every push
MIT
Get the full content and metadata of a single Paperless-ngx document by ID
Inputs: id (required).
List all correspondents defined in Paperless-ngx with their IDs and document counts
Inputs: no named parameters.
List all document types defined in Paperless-ngx with their IDs and document counts
Inputs: no named parameters.
List all tags defined in Paperless-ngx with their IDs and document counts
Inputs: no named parameters.
Get Paperless-ngx status (database status and available tasks — connectivity check)
Inputs: no named parameters.
Search Paperless-ngx documents by full-text query, returns summaries with IDs
Inputs: query (required), page.
Update metadata fields (title, correspondent, document type, tags, created date) on a Paperless-ngx document
Inputs: id (required), correspondent, created, document_type, +2 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 7 tools
Each tool has a clear and distinct purpose: retrieving a single document, searching documents, updating documents, listing correspondents/types/tags, and checking health. No overlap or ambiguity.
Tool names consistently follow a verb_noun pattern in snake_case (e.g., get_document, list_tags, search_documents). Even 'paperless_health' follows the pattern with a noun_noun structure, maintaining readability.
With 7 tools, the set is well-scoped for a Paperless-ngx MCP server. It covers core operations without being overwhelming or too sparse.
The tool set is missing crucial operations: no create_document or delete_document, and no ability to create, update, or delete correspondents, document types, or tags. This leaves significant gaps in document lifecycle management.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
