无纸化-NGX MCP服务器
用于与 Paperless-NGX API 服务器交互的 MCP（模型上下文协议）服务器。该服务器提供用于管理 Paperless-NGX 实例中的文档、标签、联系人和文档类型的工具。
快速入门
通过 Smithery 安装
要通过Smithery自动为 Claude Desktop 安装 Paperless NGX MCP 服务器：
npx -y @smithery/cli install @nloui/paperless-mcp --client claude
手动安装
- 安装 MCP 服务器：
npm install -g paperless-mcp
- 将其添加到您的 Claude 的 MCP 配置中：
对于 VSCode 扩展，编辑~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ：
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
}
}
}
对于 Claude 桌面应用程序，编辑~/Library/Application Support/Claude/claude_desktop_config.json ：
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
}
}
}
- 获取您的 API 令牌：
- 登录您的 Paperless-NGX 实例
- 点击右上角的用户名
- 选择“我的个人资料”
- 点击圆形箭头按钮生成新令牌
- 替换 MCP 配置中的占位符：
http://your-paperless-instance:8000为您的 Paperless-NGX URLyour-api-token替换为你刚刚生成的令牌
就这样！现在您可以让 Claude 帮您管理 Paperless-NGX 文档了。
示例用法
以下是您可以要求克劳德做的一些事情：
- “显示所有标记为‘发票’的文件”
- “搜索包含‘纳税申报表’的文件”
- “创建一个名为‘收据’、颜色为 #FF0000 的新标签”
- “下载文档 #123”
- “列出所有通讯员”
- “创建一个名为‘银行对账单’的新文档类型”
可用工具
文档操作
列出文档
获取所有文档的分页列表。
参数：
- page（可选）：页码
- page_size（可选）：每页文档数
list_documents({
page: 1,
page_size: 25
})
获取文档
通过 ID 获取特定文档。
参数：
get_document({
id: 123
})
搜索文档
跨文档的全文搜索。
参数：
search_documents({
query: "invoice 2024"
})
下载文档
通过 ID 下载文档文件。
参数：
- id：文档ID
- original（可选）：如果为 true，则下载原始文件而不是存档版本
download_document({
id: 123,
original: false
})
批量编辑文档
对多个文档执行批量操作。
参数：
- documents：文档 ID 数组
- 方法：以下之一：
- set_correspondent：设置文档的通讯员
- set_document_type：设置文档的文档类型
- set_storage_path：设置文档的存储路径
- add_tag：为文档添加标签
- remove_tag：从文档中删除标签
- 修改标签：添加和/或删除多个标签
- 删除：删除文档
- 重新处理：重新处理文档
- set_permissions：设置文档权限
- 合并：合并多个文档
- split：将一个文档拆分为多个文档
- 旋转：旋转文档页面
- delete_pages：从文档中删除特定页面
- 基于方法的附加参数：
- 通讯员：set_correspondent 的 ID
- document_type：set_document_type 的 ID
- storage_path：set_storage_path 的 ID
- 标签：add_tag/remove_tag 的 ID
- add_tags：modify_tags 的标签 ID 数组
- remove_tags：modify_tags 的标签 ID 数组
- 权限：具有所有者、权限、合并标志的 set_permissions 对象
- metadata_document_id：用于合并以指定元数据源的 ID
- delete_originals：合并/拆分的布尔值
- pages：用于拆分的字符串“[1,2-3,4,5-7]”或用于删除页面“[2,3,4]”
- 度数：旋转数（90、180 或 270）
例子：
// Add a tag to multiple documents
bulk_edit_documents({
documents: [1, 2, 3],
method: "add_tag",
tag: 5
})
// Set correspondent and document type
bulk_edit_documents({
documents: [4, 5],
method: "set_correspondent",
correspondent: 2
})
// Merge documents
bulk_edit_documents({
documents: [6, 7, 8],
method: "merge",
metadata_document_id: 6,
delete_originals: true
})
// Split document into parts
bulk_edit_documents({
documents: [9],
method: "split",
pages: "[1-2,3-4,5]"
})
// Modify multiple tags at once
bulk_edit_documents({
documents: [10, 11],
method: "modify_tags",
add_tags: [1, 2],
remove_tags: [3, 4]
})
后文档
将新文档上传至 Paperless-NGX。
参数：
- file：Base64编码的文件内容
- filename：文件的名称
- 标题（可选）：文档的标题
- created（可选）：文档创建的日期时间（例如“2024-01-19”或“2024-01-19 06:15:00+02:00”）
- 通讯员（可选）：通讯员的 ID
- document_type（可选）：文档类型的 ID
- storage_path（可选）：存储路径的ID
- 标签（可选）：标签 ID 数组
- archive_serial_number（可选）：存档序列号
- custom_fields（可选）：自定义字段 ID 数组
post_document({
file: "base64_encoded_content",
filename: "invoice.pdf",
title: "January Invoice",
created: "2024-01-19",
correspondent: 1,
document_type: 2,
tags: [1, 3],
archive_serial_number: "2024-001"
})
标签操作
列表标签
获取所有标签。
创建标签
创建新标签。
参数：
- 名称：标签名称
- 颜色（可选）：十六进制颜色代码（例如“#ff0000”）
- 匹配（可选）：要匹配的文本模式
- matching_algorithm（可选）：”any”，”all”，”exact”，”regular expressio”，”fuzzy”之一
create_tag({
name: "Invoice",
color: "#ff0000",
match: "invoice",
matching_algorithm: "fuzzy"
})
通讯员行动
列表通讯员
联络所有通讯员。
创建通讯员
创建新的通讯员。
参数：
- 姓名：通讯员姓名
- 匹配（可选）：要匹配的文本模式
- matching_algorithm（可选）：”any”，”all”，”exact”，”regular expressio”，”fuzzy”之一
create_correspondent({
name: "ACME Corp",
match: "ACME",
matching_algorithm: "fuzzy"
})
文档类型操作
列出文档类型
获取所有文档类型。
创建文档类型
创建一个新的文档类型。
参数：
- 名称：文档类型名称
- 匹配（可选）：要匹配的文本模式
- matching_algorithm（可选）：”any”，”all”，”exact”，”regular expressio”，”fuzzy”之一
create_document_type({
name: "Invoice",
match: "invoice total amount due",
matching_algorithm: "any"
})
错误处理
如果出现以下情况，服务器将显示清晰的错误消息：
- Paperless-NGX URL 或 API 令牌不正确
- Paperless-NGX 服务器无法访问
- 请求的操作失败
- 提供的参数无效
发展
想要贡献或修改服务器吗？以下是您需要了解的信息：
- 克隆存储库
- 安装依赖项：
- 对 server.js 进行更改
- 本地测试：
node server.js http://localhost:8000 your-test-token
该服务器由以下组件构建：
- litemcp ：用于构建 MCP 服务器的 TypeScript 框架
- zod ：TypeScript 优先模式验证
API 文档
此 MCP 服务器实现了 Paperless-NGX REST API 的端点。有关底层 API 的更多详细信息，请参阅官方文档。