星战科技xingzhan.cloud
返回市场
无纸化-mcp

无纸化-mcp

作者：baruchiro43 星标更新：2025-11-12
安装使用来源：spider==github.com

项目介绍

<!-- [![MseeP.ai 安全评估徽章](https://gips3.baidu.com/it/u=29398288,2105226654&fm=3081&app=3081&f=PNG?w=415&h=180)](https://mseep.ai/app/nloui-paperless-mcp) -->

Paperless-NGX MCP 服务器

smithery 徽章 CodeRabbit 拉取请求评审

这是一个用于与 Paperless-NGX API 服务器交互的 MCP（模型上下文协议）服务器。此服务器提供了管理 Paperless-NGX 实例中的文档、标签、联系人和文档类型的工具。

快速开始

安装 MCP 服务器

通过 Smithery 安装

要通过 Smithery 自动安装 Paperless NGX MCP 服务器到 Claude Desktop：

npx -y @smithery/cli install @baruchiro/paperless-mcp --client claude

手动安装

在你的 MCP 配置文件中添加以下内容：

// STDIO 模式（推荐用于本地或 CLI 使用）

"paperless": {
  "command": "npx",
  "args": [
    "-y",
    "@baruchiro/paperless-mcp@latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

// HTTP 模式（推荐用于 Docker 或远程使用）

"paperless": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/baruchiro/paperless-mcp:latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

  1. 获取你的 API 令牌：

    1. 登录到你的 Paperless-NGX 实例
    2. 点击右上角的用户名
    3. 选择“我的资料”
    4. 点击圆形箭头按钮生成新的令牌

  2. 替换 MCP 配置中的占位符：

    • 将 http://your-paperless-instance:8000 替换为你的 Paperless-NGX URL
    • 将 your-api-token 替换为你刚刚生成的令牌
    • 将 https://your-public-domain.com 替换为你的公共 Paperless-NGX URL（可选，默认回退到 PAPERLESS_URL）

就这样！现在你可以让 Claude 帮助你管理 Paperless-NGX 文档了。

示例用法

这里有一些你可以让 Claude 做的事情：

  • “显示所有标记为‘发票’的文档”
  • “搜索包含‘税务申报’的文档”
  • “创建一个名为‘收据’的标签，颜色为 #FF0000”
  • “下载文档 #123”
  • “列出所有联系人”
  • “创建一个名为‘银行对账单’的文档类型”

可用工具

文档操作

list_documents

获取所有文档的分页列表。

参数：

  • page（可选）：页码
  • page_size（可选）：每页的文档数量
list_documents({
  page: 1,
  page_size: 25
})

get_document

通过 ID 获取特定文档。

参数：

  • id：文档 ID
get_document({
  id: 123
})

search_documents

全文搜索文档。

参数：

  • query：搜索查询字符串
search_documents({
  query: "发票 2024"
})

download_document

通过 ID 下载文档文件。

参数：

  • id：文档 ID
  • original（可选）：如果为 true，则下载原始文件而不是归档版本
download_document({
  id: 123,
  original: false
})

bulk_edit_documents

对多个文档执行批量操作。

参数：

  • documents：文档 ID 数组
  • method：一种方法：
    • set_correspondent：设置文档的联系人
    • set_document_type：设置文档的文档类型
    • set_storage_path：设置文档的存储路径
    • add_tag：给文档添加标签
    • remove_tag：从文档移除标签
    • modify_tags：添加和/或移除多个标签
    • delete：删除文档
    • reprocess：重新处理文档
    • set_permissions：设置文档权限
    • merge：合并多个文档
    • split：将文档拆分为多个文档
    • rotate：旋转文档页面
    • delete_pages：从文档中删除特定页面
  • 根据方法的附加参数：
    • correspondent：用于 set_correspondent 的 ID
    • document_type：用于 set_document_type 的 ID
    • storage_path：用于 set_storage_path 的 ID
    • tag：用于 add_tag/remove_tag 的 ID
    • add_tags：用于 modify_tags 的标签 ID 数组
    • remove_tags：用于 modify_tags 的标签 ID 数组
    • permissions：用于 set_permissions 的对象，包括拥有者、权限和合并标志
    • metadata_document_id：用于 merge 指定元数据来源的 ID
    • delete_originals：用于 merge/split 的布尔值
    • pages：用于 split 的字符串 "[1,2-3,4,5-7]" 或 delete_pages 的 "[2,3,4]"
    • degrees：用于 rotate 的数字（90, 180 或 270）

示例：

// 给多个文档添加标签
bulk_edit_documents({
  documents: [1, 2, 3],
  method: "add_tag",
  tag: 5
})

// 设置联系人和文档类型
bulk_edit_documents({
  documents: [4,  5],
  method: "set_correspondent",
  correspondent: 2
})

// 合并文档
bulk_edit_documents({
  documents: [6, 7, 8],
  method: "merge",
  metadata_document_id: 6,
  delete_originals: true
})

// 将文档拆分为部分
bulk_edit_documents({
  documents: [9],
  method: "split",
  pages: "[1-2,3-4,5]"
})

// 一次修改多个标签
bulk_edit_documents({
  documents: [10, 11],
  method: "modify_tags",
  add_tags: [1, 2],
  remove_tags: [3, 4]
})

// 修改自定义字段
bulk_edit_documents({
  documents: [12, 13],
  method: "modify_custom_fields",
  add_custom_fields: {
    "2": "שנה"
  }
})

post_document

上传新文档到 Paperless-NGX。

参数：

  • file：Base64 编码的文件内容
  • filename：文件名
  • title（可选）：文档标题
  • created（可选）：文档创建时间（例如 "2024-01-19" 或 "2024-01-19 06:15:00+02:00"）
  • correspondent（可选）：联系人的 ID
  • document_type（可选）：文档类型的 ID
  • storage_path（可选）：存储路径的 ID
  • tags（可选）：标签 ID 数组
  • archive_serial_number（可选）：档案序列号
  • custom_fields（可选）：自定义字段 ID 数组
post_document({
  file: "base64_encoded_content",
  filename: "invoice.pdf",
  title: "一月发票",
  created: "2024-01-19",
  correspondent: 1,
  document_type: 2,
  tags: [1, 3],
  archive_serial_number: "2024-001",
  custom_fields: [1, 2]
})

标签操作

list_tags

获取所有标签。

list_tags()

create_tag

创建一个新的标签。

参数：

  • name：标签名称
  • color（可选）：十六进制颜色代码（例如 "#ff0000"）
  • match（可选）：匹配的文本模式
  • matching_algorithm（可选）：0 到 6 之间的数字： 0 - 无 1 - 任意单词 2 - 所有单词 3 - 完全匹配 4 - 正则表达式 5 - 模糊单词 6 - 自动
create_tag({
  name: "发票",
  color: "#ff0000",
  match: "invoice",
  matching_algorithm: 5
})

联系人操作

list_correspondents

获取所有联系人。

list_correspondents()

create_correspondent

创建一个新的联系人。

参数：

  • name：联系人名称
  • match（可选）：匹配的文本模式
  • matching_algorithm（可选）：0 到 6 之间的数字： 0 - 无 1 - 任意单词 2 - 所有单词 3 - 完全匹配 4 - 正则表达式 5 - 模糊单词 6 - 自动
create_correspondent({
  name: "ACME Corp",
  match: "ACME",
  matching_algorithm: 5
})

文档类型操作

list_document_types

获取所有文档类型。

list_document_types()

create_document_type

创建一个新的文档类型。

参数：

  • name：文档类型名称
  • match（可选）：匹配的文本模式
  • matching_algorithm（可选）：0 到 6 之间的数字： 0 - 无 1 - 任意单词 2 - 所有单词 3 - 完全匹配 4 - 正则表达式 5 - 模糊单词 6 - 自动
create_document_type({
  name: "发票",
  match: "发票总金额应付款项",
  matching_algorithm: 1
})

自定义字段操作

list_custom_fields

获取所有自定义字段。

list_custom_fields()

get_custom_field

通过 ID 获取特定自定义字段。

参数：

  • id：自定义字段 ID
get_custom_field({
  id: 1
})

create_custom_field

创建一个新的自定义字段。

参数：

  • name：自定义字段名称
  • data_type：一种类型："string", "url", "date", "boolean", "integer", "float", "monetary", "documentlink", "select"
  • extra_data（可选）：自定义字段的额外数据，如选择选项
create_custom_field({
  name: "发票编号",
  data_type: "string"
})

update_custom_field

更新现有的自定义字段。

参数：

  • id：自定义字段 ID
  • name（可选）：新的自定义字段名称
  • data_type（可选）：新的数据类型
  • extra_data（可选）：自定义字段的额外数据
update_custom_field({
  id: 1,
  name: "更新后的发票编号",
  data_type: "string"
})

delete_custom_field

删除自定义字段。

参数：

  • id：自定义字段 ID
delete_custom_field({
  id: 1
})

bulk_edit_custom_fields

对多个自定义字段执行批量操作。

参数：

  • custom_fields：自定义字段 ID 数组
  • operation：一种操作："delete"
bulk_edit_custom_fields({
  custom_fields: [1, 2, 3],
  operation: "delete"
})

错误处理

如果出现以下情况，服务器会显示清晰的错误信息：

  • Paperless-NGX URL 或 API 令牌不正确
  • 无法连接到 Paperless-NGX 服务器
  • 请求的操作失败
  • 提供的参数无效

开发

想要贡献或修改服务器？你需要知道以下几点：

  1. 克隆仓库
  2. 安装依赖：
npm install
  1. 对 server.js 进行更改
  2. 本地测试：
node server.js http://localhost:8000 your-test-token

该服务器构建于：

  • litemcp：一个用于构建 MCP 服务器的 TypeScript 框架
  • zod：TypeScript 优先的模式验证

API 文档

此 MCP 服务器实现了 Paperless-NGX REST API 的端点。有关底层 API 的更多细节，请参阅 官方文档。

运行 MCP 服务器

MCP 服务器可以以两种模式运行：

1. stdio（默认）

这是默认模式。服务器通过 stdio 通信，适合 CLI 和直接集成。

npm run start -- <baseUrl> <token>

2. HTTP（流式 HTTP 传输）

要作为 HTTP 服务运行服务器，请使用 --http 标志。您还可以指定端口 --port（默认：3000）。此模式需要安装 Express（它被包含为依赖项）。

npm run start -- <baseUrl> <token> --http --port 3000
  • MCP API 在指定端口上的 POST /mcp 可用。
  • 每个请求都按状态无关的方式处理，遵循 StreamableHTTPServerTransport 模式。
  • 对 /mcp 的 GET 和 DELETE 请求将返回 405 方法不允许。

致谢

本项目是 nloui/paperless-mcp 的分支。感谢原作者的工作。贡献和改进可能会返回上游。

调试

要在 VS Code 中调试 MCP 服务器，请使用以下启动配置：

{
    "type": "node",
    "request": "launch",
    "name": "调试 Paperless MCP (HTTP, ts-node ESM)",
    "program": "${workspaceFolder}/node_modules/ts-node/dist/bin.js",
    "args": [
        "--esm",
        "src/index.ts",
        "--http",
        "--baseUrl",
        "http://your-paperless-instance:8000",
        "--token",
        "your-api-token",
        "--port",
        "3002"
    ],
    "env": {
        "NODE_OPTIONS": "--loader ts-node/esm",
    },
    "console": "integratedTerminal",
    "skipFiles": [
        "<node_internals>/**"
    ]
}

重要： 在调试之前，请取消注释 src/index.ts 中的以下行（大约第 175 行）：

// await new Promise((resolve) => setTimeout(resolve, 1000000));

这可以防止服务器立即退出，并允许你设置断点和调试代码。