Paperless-ngx 文档管理
通过 9 个领域中的 42 个 MCP 工具编排 Paperless-ngx。
工具目录
文档（7 个工具）
| 工具 | 操作 | 关键参数 |
|---|
search_documents | 全文搜索 | query、page、page_size |
get_document | 完整详情 | id |
update_document | 修改单个文档 | id、title、archive_serial_number、custom_fields、note |
delete_document_note | 删除备注 | id、note_id |
post_document | 上传文件 | file_path（本地）或 file（base64）、元数据 |
download_document | 获取文件 base64 | id、original（布尔值） |
bulk_edit_documents | 批量操作 | documents（ID）、method、参数 |
标签（6 个工具）
| 工具 | 操作 |
|---|
list_tags | 所有标签、颜色和匹配规则 |
get_tag | 按 ID 获取单个标签 |
create_tag | 新建标签，可选自动匹配 |
update_tag | 修改名称、颜色和匹配规则 |
delete_tag | 已弃用 — 请使用 bulk_edit_tags 的 operation=delete |
bulk_edit_tags | 批量修改权限或删除 |
联系人（5 个工具）
| 工具 | 操作 |
|---|
list_correspondents | 所有联系人 |
get_correspondent | 按 ID 获取单个联系人 |
create_correspondent | 新建联系人，可选自动匹配 |
update_correspondent | 修改名称和匹配规则 |
bulk_edit_correspondents | 批量修改权限或删除 |
文档类型（5 个工具）
| 工具 | 操作 |
|---|
list_document_types | 所有文档类型 |
get_document_type | 按 ID 获取单个类型 |
create_document_type | 新建类型，可选自动匹配 |
update_document_type | 修改名称和匹配规则 |
bulk_edit_document_types | 批量修改权限或删除 |
存储路径（4 个工具）
| 工具 | 操作 |
|---|
list_storage_paths | 所有存储路径 |
create_storage_path | 新建路径模板和自动匹配规则 |
update_storage_path | 修改名称、模板和匹配规则 |
bulk_edit_storage_paths | 批量修改权限或删除 |
自定义字段（4 个工具）
| 工具 | 操作 |
|---|
list_custom_fields | 所有字段定义和 ID |
create_custom_field | 新建字段（名称和数据类型） |
update_custom_field | 修改名称、数据类型和选项 |
delete_custom_field | 删除一个字段及其所有值 |
任务（2 个工具）
| 工具 | 操作 |
|---|
get_task | 获取 post_document UUID 对应任务的状态和生成的文档 ID |
list_tasks | 按从新到旧列出近期任务；按状态或名称筛选，最多 100 个 |
垃圾箱（3 个工具）
| 工具 | 操作 |
|---|
list_trash | 查看等待清除的软删除文档 |
restore_from_trash | 恢复文档并保留其元数据 |
empty_trash | 永久清除（全部文档或指定 ID） |
邮件（6 个工具）
| 工具 | 操作 |
|---|
list_mail_accounts | 查看已轮询的账户（已移除凭据） |
process_mail_account | 立即触发邮件轮询 |
list_mail_rules | 查看决定导入内容的筛选条件 |
create_mail_rule | 创建导入规则（筛选条件 + 分配） |
update_mail_rule | 修改筛选条件／分配／启用状态 |
delete_mail_rule | 删除规则（仅影响后续导入） |
决策树
查找文档
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]")
整理文档
What operation?
├─ Rename title → update_document(id=N, title="...")
├─ Set/clear ASN → update_document(id=N, archive_serial_number=N|null)
├─ Custom fields → update_document(id=N, custom_fields=[{field, value}]) (IDs via list_custom_fields)
├─ Add note → update_document(id=N, note="...")
├─ Remove note → delete_document_note(id=N, note_id=NID)
├─ 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])
├─ Reprocess OCR → bulk_edit_documents(method="reprocess")
├─ Delete → bulk_edit_documents(method="delete") → goes to TRASH
├─ Undo a delete → list_trash → restore_from_trash(documents=[...])
└─ Purge for good → empty_trash(documents=[...]) !! PERMANENT !!
上传文档
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_path="~/Downloads/name.pdf", tags=[...], correspondent=ID, ...)
→ returns a task UUID, not a document ID
(file=<base64> + filename also works, but only for small files)
3. get_task(task_id=<uuid>) until status="SUCCESS"
→ related_document holds the new document ID
Lost the UUID? → list_tasks(task_name="consume_file") shows recent uploads;
list_tasks(status="FAILURE") shows rejected ones (e.g. duplicates)
管理分类体系（标签／联系人／类型）
Need to change metadata objects?
├─ View all → list_tags / list_correspondents / list_document_types /
│ list_storage_paths / list_custom_fields
│ (all take an optional name= substring filter)
├─ Resolve one ID → get_tag / get_correspondent / get_document_type
├─ Create new → create_tag / create_correspondent / create_document_type /
│ create_storage_path / create_custom_field
├─ Edit tag → update_tag(id, name, color, match, matching_algorithm)
├─ Edit sender → update_correspondent(id, name, match, matching_algorithm)
├─ Edit type → update_document_type(id, name, match, matching_algorithm)
├─ Edit storage path → update_storage_path(id, name, path, match, matching_algorithm)
├─ Edit custom field → update_custom_field(id, name, data_type, extra_data)
├─ Batch delete/perm → bulk_edit_tags / bulk_edit_correspondents /
│ bulk_edit_document_types / bulk_edit_storage_paths
└─ Del custom field → delete_custom_field(id) !! drops values from all docs !!
重要说明
- search_documents 会剥除
content，以节省令牌。要获取完整的 OCR 文本，请使用 get_document。
- post_document 优先使用
file_path：MCP 服务会从自身文件系统读取文件，因此不受大小限制。内联 Base64（file + filename）会经过模型传递，因此仅适用于小文件。file_path 仅适用于 stdio 传输；HTTP 传输会拒绝它。
- matching_algorithm 在所有端点（标签、联系人、文档类型）中都是整数
0-6：0=无，1=任一，2=全部，3=精确，4=正则表达式，5=模糊，6=自动。请参阅 tools.md。
- 邮件规则会影响未来的导入。 create/update/delete_mail_rule 会更改下次轮询邮件时导入的内容；已导入的文档不受影响。请将
enabled=false 设为暂停，而不是删除。邮件账户凭据不会出现在响应中，也无法通过 MCP 设置（仅限网页 UI）。
- 文档二进制文件是 MCP 资源：通过 resources/read 读取
paperless://documents/{id}/archive|original|thumbnail，而不是通过 download_document 拉取 Base64；也可以向 download_document 传递 as_resource_link=true 以获取链接。缩略图是轻量预览，无需读取完整文件。
- 删除文档属于软删除：
bulk_edit_documents(method="delete") 会将文档移至回收站；在保留期结束或通过 empty_trash 清空之前，可使用 restore_from_trash 还原。分类数据删除（标签、联系人、文档类型、存储路径、自定义字段）会立即永久生效。
- download_document 会返回 Base64 数据块，以及从 content-disposition 中提取的文件名。
- list_tags、list_correspondents 和 list_document_types 会返回完整的分页结果集；请使用
results 中的 ID，不要只使用独立的 all ID 列表。
- bulk_edit_documents 接受顶层 MCP 字段，但 Paperless 在内部接收的是嵌套的
parameters 对象。MCP 工具只会转发与所选 method 相关的字段。
- update_document 仅支持单个文档（标题、ASN、自定义字段、备注）。后端批量端点没有
set_title 方法——请使用 update_document 重命名；标签、联系人和类型则应通过 bulk_edit_documents 设置。note 会追加一条备注（备注在内部通过单独的 Paperless 端点存储）；使用 delete_document_note 删除备注。
- 备注是只追加的日志。 一个文档可以有多条备注，每条备注都有自己的时间戳和作者。没有编辑操作——API 和网页 UI 都不支持，这是日志语义的设计要求。要更正较早的备注，请追加一条新备注（例如“更正：……”）。只有在确实必须删除条目时才使用
delete_document_note——删除会改写历史记录。
- post_document 返回的是任务 UUID，而不是文档 ID。 轮询
get_task(task_id)，直到 status="SUCCESS"；此时 related_document 中会包含生成的文档 ID。
- 自定义字段值需要使用 list_custom_fields 返回的 ID。 调用
update_document.custom_fields 或 bulk_edit_documents.modify_custom_fields 之前，请先在那里将字段名称解析为数字 ID。
- delete_tag 已弃用（将在 v3.0.0 中移除）——请使用
bulk_edit_tags，并设置 operation="delete"；联系人、文档类型和存储路径也采用相同方式。
- delete_custom_field 仅支持单个删除——后端没有自定义字段的批量端点。删除不可撤销，并会从所有使用该字段的文档中移除其值。
参考资料
