paperless_documents_searchLABSCO SUMMARY
The whole archive, with the destructive edge deliberately blunt.
Coverage is the headline — every entity, full CRUD — but the interesting design choice is the outbox. Exporting a document writes it to a shared volume and hands back a path, so a mail server on the other side of that volume can attach the file while the bytes never enter the conversation. Mount the volume into both containers or the export is unreachable outside the container that wrote it.
What it is
A server over the Paperless-ngx API covering every entity type in the archive: documents, tags, correspondents, document types, storage paths and custom fields. It exists so "tag all 2024 invoices" is one instruction rather than an afternoon in the web UI.
What you get
- Full create-read-update-delete on every entity type
- paperless_documents_search does full-text search with filters; paperless_documents_get returns one document with all its metadata
- paperless_documents_upload takes base64 and paperless_documents_upload_from_path takes a file path; paperless_documents_reprocess re-runs OCR
- paperless_documents_bulk_update edits many documents in one call — bulk operations default to dry-run
- paperless_tags_create sets colour, matching rules and a hierarchical parent; paperless_tags_update can change or clear that parent
- paperless_custom_fields_create defines your own metadata as string, date, number or monetary, and paperless_custom_fields_assign attaches a value to a document
- paperless_documents_export_to_outbox writes a document's bytes to a shared directory and returns the path, so another tool can attach the file without the content passing through the model's context
- paperless_ping and paperless_capabilities answer whether the connection and token actually work
Requirements
A Paperless-ngx instance and an API token from its Django admin, supplied as PAPERLESS_BASE_URL and PAPERLESS_API_TOKEN. The quickest route is the container at ghcr.io/barryw/paperlessmcp with Streamable HTTP on port 5000 at /mcp; from source it needs the .NET 10 SDK and runs with --stdio. HTTP_TIMEOUT_SECONDS defaults to 30 and is worth raising if large full-text searches time out.
Setup effort
One command plus a key — docker run -d --name paperless-mcp --restart unless-stopped -e PAPERLESS_BASE_URL=<YOUR_PAPERLESS_BASE_URL> -e PAPERLESS_API_TOKEN=<YOUR_PAPERLESS_API_TOKEN> -p 5000:5000 -v paperless-outbox:/home/mcp/outbox ghcr.io/barryw/paperlessmcp:latest
USE CASES
01
Clearing a backlog of untagged documents
Search for the set, then update it in one bulk call — which previews rather than applies until you say otherwise.
02
Filing something you just scanned
Upload the file, then set its title, tags and correspondent in the same conversation.
03
Sending a document on without pushing it through the model
Export writes the file into a shared directory and returns its path, filename, mime type and size.
04
Reorganising how the archive is classified
Tags carry colour, matching rules and a parent; storage paths carry templates; custom fields add your own metadata.
05
Working out why nothing comes back
A ping tells you whether it is the URL, the token, or the query.
44 tools
Listed in project docs. Your client may show a different list.
paperless_documents_getpaperless_documents_uploadpaperless_documents_upload_from_pathpaperless_documents_updatepaperless_documents_deletepaperless_documents_bulk_updatepaperless_documents_downloadpaperless_documents_export_to_outboxpaperless_documents_previewpaperless_documents_thumbnailpaperless_documents_reprocesspaperless_tags_listpaperless_tags_getpaperless_tags_createpaperless_tags_updatepaperless_tags_deletepaperless_tags_bulk_deletepaperless_correspondents_listpaperless_correspondents_getpaperless_correspondents_createpaperless_correspondents_updatepaperless_correspondents_deletepaperless_correspondents_bulk_deletepaperless_document_types_listpaperless_document_types_getpaperless_document_types_createpaperless_document_types_updatepaperless_document_types_deletepaperless_document_types_bulk_deletepaperless_storage_paths_listpaperless_storage_paths_getpaperless_storage_paths_createpaperless_storage_paths_updatepaperless_storage_paths_deletepaperless_storage_paths_bulk_deletepaperless_custom_fields_listpaperless_custom_fields_getpaperless_custom_fields_createpaperless_custom_fields_updatepaperless_custom_fields_deletepaperless_custom_fields_assignpaperless_pingpaperless_capabilitiesBEFORE YOU INSTALL
What to know first
Tools you get
44 tools named in the project's documentation.
Requires
- Docker
- A Paperless-ngx instance with an API token (Settings → Django Admin → Tokens)
- PAPERLESS_BASE_URL and PAPERLESS_API_TOKEN passed to the container
INSTALLATION
Connect your client
Server setup
TERMINAL
docker run -d --name paperless-mcp --restart unless-stopped -e PAPERLESS_BASE_URL=<YOUR_PAPERLESS_BASE_URL> -e PAPERLESS_API_TOKEN=<YOUR_PAPERLESS_API_TOKEN> -p 5000:5000 -v paperless-outbox:/home/mcp/outbox ghcr.io/barryw/paperlessmcp:latestThe latest tag always exists; for a reproducible deployment, pin a versioned tag from the project releases page instead.
MCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add --transport http paperless http://localhost:5000/mcpLiteLLM Proxy
LITELLM PROXY · YAML
mcp_servers:
paperless:
url: "http://paperless-mcp:5000/mcp"
transport: "http"
description: "Paperless-ngx document management"
