Model Context Protocol server for Paperless-ngx

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
120+tools covering the REST API
2.x & 3.xPaperless-ngx, API version pinned
stdio + HTTPsingle- or multi-user
MITopen source, self-hosted

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.

“Find all invoices from my ISP in 2025 and tag them as telecom.”
“Upload this PDF, set the correspondent to my landlord, and file it as a contract.”
“Which documents in my inbox are missing a correspondent or document type?”
“Give me just the page of my insurance policy that mentions the deductible.”
“Which bank statements from last year are missing compared to this year?”
“Find the document about the espresso machine warranty.” Semantic search: no keyword match needed.

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_documents
  • search_autocomplete
  • list_documents
  • get_document
  • get_documents
  • download_document
  • update_document
  • delete_document
  • upload_document
  • get_document_metadata
  • get_document_suggestions
  • get_document_notes
  • add_document_note
  • delete_document_note
  • get_document_history
  • get_document_thumbnail
  • get_document_content
  • upload_from_url
Bulk operations 6
  • bulk_edit_documents
  • bulk_set_object_permissions
  • bulk_download_documents
  • get_next_asn
  • get_selection_data
  • test_storage_path
Organization 28
  • list_tags
  • get_tag
  • create_tag
  • update_tag
  • delete_tag
  • list_correspondents
  • get_correspondent
  • create_correspondent
  • update_correspondent
  • delete_correspondent
  • list_document_types
  • get_document_type
  • create_document_type
  • update_document_type
  • delete_document_type
  • list_storage_paths
  • get_storage_path
  • create_storage_path
  • update_storage_path
  • delete_storage_path
  • list_custom_fields
  • get_custom_field
  • create_custom_field
  • update_custom_field
  • list_saved_views
  • get_saved_view
  • create_saved_view
  • update_saved_view
AI workflows and helpers 9
  • auto_classify_document
  • process_inbox
  • bulk_tag_by_content
  • get_documents_by_correspondent
  • monthly_summary
  • yearly_document_check
  • extract_document_pages
  • find_document_pages
  • get_document_ai_suggestions3.0+
Semantic search 3
  • semantic_search
  • sync_embeddings
  • embedding_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_users
  • get_user
  • create_user
  • update_user
  • list_groups
  • get_group
  • create_group
  • update_group
  • list_workflows
  • get_workflow
  • create_workflow
  • update_workflow
  • run_workflow3.5+
Mail 11
  • list_mail_accounts
  • get_mail_account
  • create_mail_account
  • update_mail_account
  • test_mail_account
  • process_mail_account
  • list_mail_rules
  • get_mail_rule
  • create_mail_rule
  • update_mail_rule
  • list_processed_mail
Sharing and email 10
  • list_share_links
  • get_share_link
  • create_share_link
  • get_document_share_links
  • list_share_link_bundles3.0+
  • get_share_link_bundle3.0+
  • create_share_link_bundle3.0+
  • rebuild_share_link_bundle3.0+
  • email_document
  • email_documents
System, tasks and trash 18
  • get_status
  • get_statistics
  • list_tasks
  • acknowledge_tasks
  • run_task3.0+
  • get_task_summary3.0+
  • get_task_status_counts3.0+
  • get_active_tasks3.0+
  • get_config
  • update_config
  • get_ui_settings
  • get_profile
  • get_remote_version
  • list_logs
  • get_log
  • list_trash
  • restore_from_trash
  • empty_trash
Prompts 5
  • triage_inbox
  • tax_prep
  • monthly_review
  • find_document
  • cleanup_tags
Resources 7
  • paperless://tags
  • paperless://correspondents
  • paperless://document-types
  • paperless://storage-paths
  • paperless://custom-fields
  • paperless://saved-views
  • paperless://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=true for 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