Let your AI assistant run your paperwork.
paperless-mcp connects Claude and any other MCP client to your Paperless-ngx archive. Search, upload, tag, split and share documents in plain language, with optional semantic search across everything you have ever scanned.
claude mcp add paperless \
--env PAPERLESS_URL=https://paperless.example.com \
--env PAPERLESS_TOKEN=your-api-token \
-- npx -y @orellbuehler/paperless-mcp
Everything Paperless can do, through conversation
Not a thin search wrapper. paperless-mcp covers documents, metadata, permissions, mail, workflows and system administration, and adds tools built for agents on top.
Full document management
Search, upload, download, update and bulk-edit documents. Manage tags, correspondents, document types, storage paths, custom fields and saved views.
Semantic search
Find documents by meaning, not keywords. Embeddings from OpenAI or Ollama, stored locally in sqlite-vec. No external vector database.
AI-assisted workflows
Auto-classify documents, triage the inbox, bulk-tag by content, and spot missing recurring documents year over year, for example when preparing taxes.
PDF page tools
Pull out just the page that matters as a new PDF, or find which pages mention a phrase. Processed locally, without touching the original.
Multi-user and OAuth
Run one HTTP server for the whole household or team. Every request runs as the signed-in user, with their own Paperless permissions. Optional OIDC sign-in, with sessions that survive restarts in an encrypted state file.
Mail, sharing and trash
Configure mail accounts and rules, create public share links and bundles, email documents, and restore from the trash.
Paperless-ngx 3.5 ready
Document versions, PDF editing, manual workflow runs, barcode contents, share bundles and task management, including the background bulk edits of 3.5. API v9 is pinned by default so 2.x and 3.x behave the same; v10 is fully supported when you opt in.
Safe by design
Every tool is annotated as read-only, destructive or external, so clients can auto-approve reads and confirm deletes. Run read-only, or load only the toolsets you need.
Docker sidecar
Prebuilt image on GHCR. Drop it next to Paperless in your compose stack and point
your clients at /mcp.
Vision-ready
Thumbnails and image documents come back as images, so vision models can look at a receipt or a scan instead of guessing from OCR text.
Prompts and resources
Ready-made prompts for inbox triage, tax prep and tag cleanup, plus resources that load your tags, correspondents and document types as context.
Resilient connection
Request timeouts and automatic retries for safe reads, honouring
Retry-After, so a slow or restarting Paperless doesn't hang your agent.
Ask, don't click
Things you can say once it's connected.
Tool catalog
Grouped by area, plus MCP prompts and resources. Expand a group to see its entries; the README has the details.
Documents and search 18
search_documentssearch_autocompletelist_documentsget_documentget_documentsdownload_documentupdate_documentdelete_documentupload_documentget_document_metadataget_document_suggestionsget_document_notesadd_document_notedelete_document_noteget_document_historyget_document_thumbnailget_document_contentupload_from_url
Bulk operations 6
bulk_edit_documentsbulk_set_object_permissionsbulk_download_documentsget_next_asnget_selection_datatest_storage_path
Organization 28
list_tagsget_tagcreate_tagupdate_tagdelete_taglist_correspondentsget_correspondentcreate_correspondentupdate_correspondentdelete_correspondentlist_document_typesget_document_typecreate_document_typeupdate_document_typedelete_document_typelist_storage_pathsget_storage_pathcreate_storage_pathupdate_storage_pathdelete_storage_pathlist_custom_fieldsget_custom_fieldcreate_custom_fieldupdate_custom_fieldlist_saved_viewsget_saved_viewcreate_saved_viewupdate_saved_view
AI workflows and helpers 9
auto_classify_documentprocess_inboxbulk_tag_by_contentget_documents_by_correspondentmonthly_summaryyearly_document_checkextract_document_pagesfind_document_pagesget_document_ai_suggestions3.0+
Semantic search 3
semantic_searchsync_embeddingsembedding_status
Versions and PDF editing 10
upload_document_version3.0+set_document_version_label3.0+delete_document_version3.0+get_document_root3.0+rotate_documents3.0+merge_documents3.0+merge_documents_as_versions3.1+edit_pdf_document3.0+remove_document_password3.0+reprocess_documents3.0+
Users, groups and workflows 13
list_usersget_usercreate_userupdate_userlist_groupsget_groupcreate_groupupdate_grouplist_workflowsget_workflowcreate_workflowupdate_workflowrun_workflow3.5+
Mail 11
list_mail_accountsget_mail_accountcreate_mail_accountupdate_mail_accounttest_mail_accountprocess_mail_accountlist_mail_rulesget_mail_rulecreate_mail_ruleupdate_mail_rulelist_processed_mail
Sharing and email 10
list_share_linksget_share_linkcreate_share_linkget_document_share_linkslist_share_link_bundles3.0+get_share_link_bundle3.0+create_share_link_bundle3.0+rebuild_share_link_bundle3.0+email_documentemail_documents
System, tasks and trash 18
get_statusget_statisticslist_tasksacknowledge_tasksrun_task3.0+get_task_summary3.0+get_task_status_counts3.0+get_active_tasks3.0+get_configupdate_configget_ui_settingsget_profileget_remote_versionlist_logsget_loglist_trashrestore_from_trashempty_trash
Prompts 5
triage_inboxtax_prepmonthly_reviewfind_documentcleanup_tags
Resources 7
paperless://tagspaperless://correspondentspaperless://document-typespaperless://storage-pathspaperless://custom-fieldspaperless://saved-viewspaperless://documents/{id}
Run it your way
Start with one command on your laptop, or run a shared server next to Paperless.
stdio, single user
Your MCP client launches the server via npx. Nothing to host.
- Claude Code, Claude Desktop, any MCP client
- Uses your Paperless API token
- Semantic index stored in
~/.paperless-mcp PAPERLESS_READ_ONLY=truefor a look-but-don't-touch assistant
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": ["-y", "@orellbuehler/paperless-mcp"],
"env": {
"PAPERLESS_URL": "https://paperless.example.com",
"PAPERLESS_TOKEN": "your-api-token"
}
}
}
}
HTTP sidecar, multi-user
One server for everyone. Each request runs with the caller's own token.
- Prebuilt Docker image on GHCR
- Optional OAuth sign-in via your Paperless OIDC provider
- Shared semantic index, filtered per user
paperless-mcp:
image: ghcr.io/orellbuehler/paperless-mcp:latest
ports: ["3001:3001"]
volumes: ["./mcp:/data"]
environment:
PAPERLESS_URL: http://webserver:8000
PAPERLESS_TOKEN: <admin-token>
Compatibility
The client pins REST API v9 by default, so behavior doesn't change when you upgrade
Paperless. Opt into v10 with PAPERLESS_API_VERSION=10, or set it to
none to follow the server.
| Capability | Paperless-ngx 2.x | Paperless-ngx 3.x |
|---|---|---|
| Documents, organization, mail, sharing, users, workflows | Yes | Yes |
| Semantic search, PDF page tools, AI workflows | Yes | Yes |
| Rotate, merge, split | Via bulk_edit_documents |
Yes |
| Document versions, PDF editing, AI suggestions | No | Yes |
| Share link bundles, task management | No | Yes |