内容
# paperless-ngx-mcp
[](https://github.com/cubinet-code/paperless-ngx-mcp/actions/workflows/ci.yml)
[](LICENSE)
一款适用于 [Paperless-NGX](https://docs.paperless-ngx.com/) 的[模型上下文协议](https://modelcontextprotocol.io/) 服务器。为 AI 助手提供完整的 Paperless-NGX REST API 接口——文件、标签、通讯者、文件类型、自定义字段、存储路径、保存的视图、分享链接、工作流程、笔记、回收站和任务。
## 快速开始
服务器已发布到 npm，名为 [`paperless-ngx-mcp`](https://www.npmjs.com/package/paperless-ngx-mcp)。您可以使用 `npx` 运行它，无需克隆或构建。
### Claude 代码
```bash
claude mcp add paperless --scope user \
--env PAPERLESS_URL=https://your-paperless-instance \
--env PAPERLESS_API_KEY=your-api-token \
-- npx -y paperless-ngx-mcp
```
删除 `--scope user` 以仅为当前项目安装。更多选项请参见 `claude mcp add --help`。
### Codex CLI
```bash
codex mcp add paperless \
--env PAPERLESS_URL=https://your-paperless-instance \
--env PAPERLESS_API_KEY=your-api-token \
-- npx -y paperless-ngx-mcp
```
这会将条目写入 `~/.codex/config.toml`。
### Claude 桌面版、Cursor、Cline 及其他 MCP 客户端
将以下内容添加到客户端的 MCP 配置文件（例如 `claude_desktop_config.json`、`~/.cursor/mcp.json`、`~/.config/cline/mcp.json`）：
```json
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": ["-y", "paperless-ngx-mcp"],
"env": {
"PAPERLESS_URL": "https://your-paperless-instance",
"PAPERLESS_API_KEY": "your-api-token",
"PAPERLESS_PUBLIC_URL": "https://your-public-domain"
}
}
}
}
```
### 获取 Paperless-NGX API 令牌
1. 登录到您的 Paperless-NGX 实例。
2. 点击您的用户名（右上角）→ **我的个人资料**。
3. 点击圆形箭头按钮以生成新的令牌。
### 配置
| 变量 | 必需 | 用途 |
|---|---|---|
| `PAPERLESS_URL` | 是 | MCP 服务器用于与 Paperless-NGX 通信的基准 URL。 |
| `PAPERLESS_API_KEY` | 是 | API 令牌（参见上文）。 |
| `PAPERLESS_PUBLIC_URL` | 否 | 公共 URL，用于构造指向文档的浏览器链接。默认为 `PAPERLESS_URL`。 |
CLI 标志（ `--baseUrl`、 `--token`、 `--publicUrl`、 `--http`、 `--port` ）的优先级高于环境变量。
### 示例用法
您可以向 Claude（或任何 MCP 感知助手）提出的问题：
- "显示所有标记为 'Invoice' 的文件"
- "搜索包含 'tax return' 的文件"
- "创建一个名为 'Receipts' 的新标签，颜色为 #FF0000"
- "下载文件 #123"
- "列出所有通讯者"
- "创建一个名为 'Bank Statement' 的新文件类型"
- "清空回收站"
- "显示待处理的消费任务"
## 可用工具
服务器在十个领域注册工具。
### 文件
`list_documents`、`get_document`、`get_document_content`、`search_documents`、`download_document`、`download_documents_bulk`、`get_document_thumbnail`、`get_document_preview`、`get_document_history`、`get_document_metadata`、`update_document`、`post_document`、`email_document`、`edit_documents_bulk`、`delete_document`、`search_autocomplete`、`get_document_suggestions`、`get_next_asn`
### 标签
`list_tags`、`get_tag`、`create_tag`、`update_tag`、`delete_tag`、`edit_tags_bulk`
### 通讯者
`list_correspondents`、`get_correspondent`、`create_correspondent`、`update_correspondent`、`delete_correspondent`、`edit_correspondents_bulk`
### 文件类型
`list_document_types`、`get_document_type`、`create_document_type`、`update_document_type`、`delete_document_type`、`edit_document_types_bulk`
### 自定义字段
`list_custom_fields`、`get_custom_field`、`create_custom_field`、`update_custom_field`、`delete_custom_field`、`edit_custom_fields_bulk`
### 存储路径
`list_storage_paths`、`get_storage_path`、`create_storage_path`、`update_storage_path`、`delete_storage_path`、`test_storage_path`
### 保存的视图
`list_saved_views`、`get_saved_view`、`create_saved_view`、`update_saved_view`、`delete_saved_view`
### 分享链接
`list_share_links`、`list_document_share_links`、`get_share_link`、`create_share_link`、`update_share_link`、`delete_share_link`
### 工作流程
`list_workflow_actions`、`get_workflow_action`、`create_workflow_action`、`update_workflow_action`、`delete_workflow_action`、`list_workflow_triggers`、`get_workflow_trigger`、`create_workflow_trigger`、`update_workflow_trigger`、`delete_workflow_trigger`
### 系统 / 笔记 / 回收站 / 任务
`get_statistics`、`list_document_notes`、`create_document_note`、`delete_document_note`、`list_trash`、`restore_from_trash`、`empty_trash`、`list_tasks`、`acknowledge_tasks`
### 工具命名约定（用于权限允许列表）
工具名称 **以动词开头**，因此基于通配符的权限规则按操作分组：
| 通配符 | 涵盖范围 |
|---|---|
| `mcp__paperless__list_*` | 所有列表/索引读取 |
| `mcp__paperless__get_*` | 所有单项读取 |
| `mcp__paperless__search_*` | 全文搜索和自动补全 |
| `mcp__paperless__download_*` | `download_document` 和 `download_documents_bulk` |
| `mcp__paperless__create_*` | 所有创建端点 |
| `mcp__paperless__update_*` | 按项目 PATCH 更新 |
| `mcp__paperless__edit_*_bulk` | 跨实体类型的批量编辑操作 |
| `mcp__paperless__delete_*` | ⚠️ 销毁性 - 系统范围删除 |
因此，只读权限列表为：`list_*`、`get_*`、`search_*`、`download_*`。写入权限（无销毁操作）：添加 `create_*`、`update_*`、`edit_*_bulk`、`post_document`、`email_document`。`delete_*` 和 `empty_trash` 应需要明确的用户批准。
## 提示
服务器还注册了 MCP **提示** - 可重用的、参数化的指令，作为 Claude Code 等客户端（如 `/mcp__paperless__triage_inbox`）的斜线命令。
### `triage_inbox`
引导助手完成收件箱分类：收集现有的标签 / 通讯者 / 文件类型，为每个收件箱文件提出元数据 **优先使用现有项目**，显示确认表格，仅在用户回复 `apply` 后应用更改。新通讯者 / 类型 / 标签被标记为 `(NEW)`，以便您可以否决创建操作。
参数：
- `limit`（可选，默认为 `25`）：一次通过分类的最大收件箱文件数。
### 值得注意的工具详情
#### `edit_documents_bulk`
对多个文件执行批量操作。
参数：
- `documents`：文件 ID 数组
- `method`：`set_correspondent`、`set_document_type`、`set_storage_path`、`add_tag`、`remove_tag`、`modify_tags`、`modify_custom_fields`、`delete`、`reprocess`、`set_permissions`、`merge`、`split`、`rotate`、`delete_pages`、`edit_pdf` 之一
- 方法特定参数：`correspondent`、`document_type`、`storage_path`、`tag`、`add_tags`、`remove_tags`、`add_custom_fields`、`remove_custom_fields`、`set_permissions`、`owner`、`merge`、`metadata_document_id`、`delete_originals`、`pages`、`degrees`、`operations`、`update_document`、`include_metadata`
```typescript
// 为多个文件添加标签
edit_documents_bulk({ documents: [1, 2, 3], method: "add_tag", tag: 5 })
// 合并文件
edit_documents_bulk({
documents: [6, 7, 8],
method: "merge",
metadata_document_id: 6,
delete_originals: true,
})
// 将文件分成部分
edit_documents_bulk({ documents: [9], method: "split", pages: "[1-2,3-4,5]" })
// 同时修改多个标签
edit_documents_bulk({
documents: [10, 11],
method: "modify_tags",
add_tags: [1, 2],
remove_tags: [3, 4],
})
```
#### `post_document`
上传新文件。
参数：`file`（base64 编码内容）、 `filename`，以及可选的 `title`、`created`、`correspondent`、`document_type`、`storage_path`、`tags`、`archive_serial_number`、`custom_fields`。
#### 匹配算法
`create_tag`、`create_correspondent`、`create_document_type` 和 `create_storage_path` 接受一个 `matching_algorithm`（0-6）：
| 值 | 含义 |
|---|---|
| 0 | 无 |
| 1 | 任意字 |
| 2 | 所有字 |
| 3 | 精确匹配 |
| 4 | 正则表达式 |
| 5 | 模糊字 |
| 6 | 自动 |
## 运行 MCP 服务器
### 标准输入输出（默认）
默认模式。服务器通过标准输入输出进行通信 - 这是快速入门中所有 MCP 客户端配置使用的模式。通常您不会手动运行它；MCP 客户端为您启动它。
如果您想直接运行它（例如用于调试）：
```bash
# 使用环境变量（推荐）
PAPERLESS_URL=http://localhost:8000 PAPERLESS_API_KEY=xxx npx -y paperless-ngx-mcp
# 或使用 CLI 标志
npx -y paperless-ngx-mcp --baseUrl http://localhost:8000 --token xxx
```
### HTTP（可流式传输的 HTTP 传输）
使用 `--http` 标志将服务器公开在 HTTP 上。 `--port` 默认为 `3000`。
```bash
npx -y paperless-ngx-mcp --baseUrl http://localhost:8000 --token xxx --http --port 3000
```
- MCP API 在所选端口的 `POST /mcp` 上可用。
- 每个请求都通过 [`StreamableHTTPServerTransport`](https://github.com/modelcontextprotocol/typescript-sdk) 无状态处理。
- 还为不支持流式传输的客户端公开了一个旧的 `GET /sse` + `POST /messages` SSE 传输。
## 错误处理
工具调用在以下情况下返回明确的错误：
- `PAPERLESS_URL` 或 `PAPERLESS_API_KEY` 缺失或错误
- Paperless-NGX 服务器无法访问
- 底层 API 拒绝操作
- 工具参数验证失败
## 开发
如果您正在修改服务器本身，则只需要此部分。终端用户应遵循 [快速入门](#快速入门) 而不是克隆或构建。
```bash
git clone https://github.com/cubinet-code/paperless-ngx-mcp.git
cd paperless-ngx-mcp
npm install # 安装依赖
npm run start # 使用 tsx 运行服务器（无构建步骤）
npm run build # 将 TypeScript 编译为 build/
npm test # 单元测试（node:test + tsx）
npm run inspect # 构建，然后启动 @modelcontextprotocol/inspector
```
`npm run start` 接受与构建的二进制文件相同的标志/环境变量。
### 端到端测试
E2E 测试通过 Docker Compose 启动一个真正的 Paperless-NGX 容器：
```bash
npm run test:e2e:up # 启动测试栈（paperless + redis）
npm run test:e2e # 运行 E2E 测试套件
npm run test:e2e:down # 拆除并删除卷
```
使用以下技术构建：
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) - MCP 服务器 SDK
- [zod](https://github.com/colinhacks/zod) - 模式验证
- [axios](https://github.com/axios/axios) - HTTP 客户端（带有 keep-alive 代理和 60 秒超时）
## API 文档
此 MCP 服务器包装了 Paperless-NGX REST API 的端点。有关底层行为和字段语义的详细信息，请参见 [官方 API 文档](https://docs.paperless-ngx.com/api/)。
## 许可证
ISC。参见 [LICENSE](LICENSE)。
