paperless-ngx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paperless-ngx Document Management

Paperless-ngx 文档管理

Orchestrate Paperless-ngx through 16 MCP tools across 4 domains.

通过4个领域的16款MCP工具对Paperless-ngx进行编排管理。

Tool Catalog

工具目录

Documents (5 tools)

文档（5款工具）

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

工具名称	操作类型	关键参数
`search_documents`	全文搜索	`query` , `page` , `page_size`
`get_document`	获取完整详情	`id`
`post_document`	上传文件	`file` （base64格式）, `filename` , 元数据
`download_document`	获取文件base64	`id` , `original` （布尔值）
`bulk_edit_documents`	批量操作	`documents` （ID列表）, `method` , 参数

Tags (5 tools)

标签（5款工具）

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

工具名称	操作类型
`list_tags`	获取所有标签+颜色+匹配规则
`create_tag`	创建新标签，可选自动匹配
`update_tag`	修改名称/颜色/匹配规则
`delete_tag`	永久删除标签
`bulk_edit_tags`	批量设置权限/删除标签

Correspondents (3 tools)

联系人（3款工具）

Tool	Operation
`list_correspondents`	All correspondents
`create_correspondent`	New, optional auto-match
`bulk_edit_correspondents`	Batch permissions/delete

工具名称	操作类型
`list_correspondents`	获取所有联系人
`create_correspondent`	创建新联系人，可选自动匹配
`bulk_edit_correspondents`	批量设置权限/删除联系人

Document Types (3 tools)

文档类型（3款工具）

Tool	Operation
`list_document_types`	All document types
`create_document_type`	New, optional auto-match
`bulk_edit_document_types`	Batch permissions/delete

工具名称	操作类型
`list_document_types`	获取所有文档类型
`create_document_type`	创建新文档类型，可选自动匹配
`bulk_edit_document_types`	批量设置权限/删除文档类型

Decision Trees

决策树

Find a Document

查找文档

txt

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]")

txt

你已知哪些信息？
├─ 关键词/内容     → search_documents(query="term1 term2")
├─ 文档ID          → get_document(id=N)
├─ 按标签查找      → search_documents(query="tag:tagname")
├─ 按类型查找      → search_documents(query="type:typename")
├─ 按联系人查找    → search_documents(query="correspondent:name")
├─ 按日期查找      → search_documents(query="created:[2024 to 2025]")
└─ 组合条件查找    → search_documents(query="tag:X correspondent:Y created:[2024 to 2025]")

Organize Documents

整理文档

txt

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 !!

txt

需要执行什么操作？
├─ 添加标签         → bulk_edit_documents(method="add_tag", tag=ID)
├─ 移除标签         → bulk_edit_documents(method="remove_tag", tag=ID)
├─ 多标签修改       → bulk_edit_documents(method="modify_tags", add_tags=[...], remove_tags=[...])
├─ 设置文档类型     → bulk_edit_documents(method="set_document_type", document_type=ID)
├─ 设置发件人       → bulk_edit_documents(method="set_correspondent", correspondent=ID)
├─ 合并PDF         → bulk_edit_documents(method="merge", metadata_document_id=ID)
├─ 旋转页面         → bulk_edit_documents(method="rotate", degrees=90|180|270)
├─ 删除页面         → bulk_edit_documents(method="delete_pages", pages="1,3,5-7")
├─ 重新处理OCR      → bulk_edit_documents(method="reprocess")
└─ 删除文档         → bulk_edit_documents(method="delete")  !! 永久删除 !!

Upload a Document

上传文档

txt

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, ...)

txt

1. 先解析元数据ID：
   ├─ list_tags            → 查找或创建标签（create_tag）
   ├─ list_correspondents  → 查找或创建联系人（create_correspondent）
   └─ list_document_types  → 查找或创建文档类型（create_document_type）
2. post_document(file=<base64>, filename="name.pdf", tags=[...], correspondent=ID, ...)

Manage Taxonomy (Tags/Correspondents/Types)

管理分类体系（标签/联系人/文档类型）

txt

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

txt

需要修改元数据对象吗？
├─ 查看全部          → list_tags / list_correspondents / list_document_types
├─ 创建新对象        → create_tag / create_correspondent / create_document_type
├─ 编辑标签          → update_tag(id, name, color, match, matching_algorithm)
├─ 删除单个标签      → delete_tag(id)
├─ 批量删除/设置权限 → 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.

search_documents会剥离
content
字段以节省令牌。如需完整OCR文本，请使用
```
get_document
```
。
post_document要求文件内容为base64格式，不支持文件路径。
matching_algorithm在所有端点（标签、联系人、文档类型）中均为整数
```
0-6
```
：
```
0
```
=无，
```
1
```
=任意，
```
2
```
=全部，
```
3
```
=精确匹配，
```
4
```
=正则表达式，
```
5
```
=模糊匹配，
```
6
```
=自动匹配。详情请见tools.md。
批量删除操作是永久且不可恢复的。
download_document会返回base64二进制数据及content-disposition中的文件名。

References

参考资料

Task	File
Tool parameters & types	tools.md
Search query syntax	query-syntax.md
Multi-step workflows	workflows.md

任务	文件路径
工具参数及类型	tools.md
搜索查询语法	query-syntax.md
多步骤工作流	workflows.md