Paperless-ngx Document Management
Orchestrate Paperless-ngx through 16 MCP tools across 4 domains.
Tool Catalog
Documents (5 tools)
| Tool | Operation | Key Params |
|---|
search_documents | Full-text search | query, page, page_size |
get_document | Full details | id |
post_document | Upload file | file (base64), filename, metadata |
download_document | Get file base64 | id, original (bool) |
bulk_edit_documents | Batch operations | documents (IDs), method, params |
Tags (5 tools)
| Tool | Operation |
|---|
list_tags | All tags + colors + matching |
create_tag | New tag, optional auto-match |
update_tag | Modify name/color/matching |
delete_tag | Remove permanently |
bulk_edit_tags | Batch permissions/deletion |
Correspondents (3 tools)
| Tool | Operation |
|---|
list_correspondents | All correspondents |
create_correspondent | New, optional auto-match |
bulk_edit_correspondents | Batch permissions/delete |
Document Types (3 tools)
| Tool | Operation |
|---|
list_document_types | All document types |
create_document_type | New, optional auto-match |
bulk_edit_document_types | Batch permissions/delete |
Decision Trees
Find a Document
What do you know?
├─ Keywords/content → search_documents(query="term1 term2")
├─ Document ID → get_document(id=N)
├─ By tag → search_documents(query="tag:tagname")
├─ By type → search_documents(query="type:typename")
├─ By correspondent → search_documents(query="correspondent:name")
├─ By date → search_documents(query="created:[2024 to 2025]")
└─ Combined → search_documents(query="tag:X correspondent:Y created:[2024 to 2025]")
Organize Documents
What operation?
├─ Add tag → bulk_edit_documents(method="add_tag", tag=ID)
├─ Remove tag → bulk_edit_documents(method="remove_tag", tag=ID)
├─ Multi-tag → bulk_edit_documents(method="modify_tags", add_tags=[...], remove_tags=[...])
├─ Set type → bulk_edit_documents(method="set_document_type", document_type=ID)
├─ Set sender → bulk_edit_documents(method="set_correspondent", correspondent=ID)
├─ Merge PDFs → bulk_edit_documents(method="merge", metadata_document_id=ID)
├─ Rotate pages → bulk_edit_documents(method="rotate", degrees=90|180|270)
├─ Delete pages → bulk_edit_documents(method="delete_pages", pages="1,3,5-7")
├─ Reprocess OCR → bulk_edit_documents(method="reprocess")
└─ Delete → bulk_edit_documents(method="delete") !! PERMANENT !!
Upload a Document
1. Resolve metadata IDs first:
├─ list_tags → find or create_tag
├─ list_correspondents → find or create_correspondent
└─ list_document_types → find or create_document_type
2. post_document(file=<base64>, filename="name.pdf", tags=[...], correspondent=ID, ...)
Manage Taxonomy (Tags/Correspondents/Types)
Need to change metadata objects?
├─ View all → list_tags / list_correspondents / list_document_types
├─ Create new → create_tag / create_correspondent / create_document_type
├─ Edit tag → update_tag(id, name, color, match, matching_algorithm)
├─ Delete one tag → delete_tag(id)
├─ Batch delete/perm → bulk_edit_tags / bulk_edit_correspondents / bulk_edit_document_types
Critical Notes
- search_documents strips
content to save tokens. Use get_document for full OCR text. - post_document requires base64 file content, not file paths.
- matching_algorithm is integer
0-6 across all endpoints (tags, correspondents, document types): 0=none, 1=any, 2=all, 3=exact, 4=regex, 5=fuzzy, 6=auto. See tools.md. - Bulk delete is permanent and irreversible.
- download_document returns base64 blob + filename from content-disposition.
References
