AI导哈

文档管理MCP服务器

Paperless-NGX MCP服务器是一个用于与Paperless-NGX API服务器交互的工具，提供文档、标签、通信者和文档类型的管理功能。

  • by nloui
  • TypeScript
  • 混合部署
  • 245 星标
  • 更新于
在 GitHub 查看 nloui/paperless-mcp

使用说明

无纸化NGX MCP服务器

一种用于与无纸-NGX API服务器交互的MCP（模型上下文协议）服务器。此服务器提供用于管理无纸NGX实例中的文档、标签、通讯员和文档类型的工具。

快速开始

安装

  1. 安装MCP服务器：
npm install -g paperless-mcp
  1. 将其添加到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"]
    }
  }
}

  1. 获取您的API令牌：

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

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

    • http://your-paperless-instance:8000 使用您的无纸NGX URL
    • your-api-token 使用您刚才生成的令牌

就是这样！现在，您可以让Claude帮助您管理无纸NGX文档。

示例用法

以下是一些你可以要求克劳德做的事情：

  • “显示所有标记为“发票”的文档”
  • “搜索包含‘纳税申报单’的文档”
  • “创建一个名为'Receipts'的新标签，颜色为#FF0000”
  • “下载文档#123”
  • “列出所有通讯员”
  • “创建名为“银行对账单”的新文档类型”

可用工具

文档操作

list_文档

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

参数：

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

get_document

按ID获取特定文档。

参数：

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

搜索文档

跨文档进行全文搜索。

参数：

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

下载_文档

按ID下载文档文件。

参数：

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

bulk_edit_文档

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

参数：

  • documents：文档ID数组
  • 方法：以下方法之一：
    • set_correspondent：为文档设置通信者
    • set_document_type：设置文档的文档类型
    • set_storage_path：设置文档的存储路径
    • add_tag：为文档添加标签
    • remove_tag：从文档中删除标记
    • modify_tags：添加和/或删除多个标签
    • delete：删除文档
    • 重新处理：重新处理文档
    • set_permissions：设置文档权限
    • 合并：合并多个文档
    • split：将文档拆分为多个文档
    • rotate：旋转文档页面
    • delete_pages：从文档中删除特定页面
  • 基于方法的附加参数：
    • 通讯员：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：用于指定元数据源的合并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]
})

post_文档

将新文档上传到Paperless NGX。

参数：

  • file:Base64编码文件内容
  • filename：文件的名称
  • title（可选）：文档的标题
  • created（可选）：创建文档时的日期时间（例如“2024-01-19”或“2024年01月19日06:15:00+02:00”）
  • 通讯员（可选）：通讯员的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: "January Invoice",
  created: "2024-01-19",
  correspondent: 1,
  document_type: 2,
  tags: [1, 3],
  archive_serial_number: "2024-001"
})

标签操作

list_tags

获取所有标签。

list_tags()

create_tag

创建一个新标签。

参数：

  • name:标签名称
  • 颜色（可选）：十六进制颜色代码（例如“#ff0000”）
  • match（可选）：要匹配的文本模式
  • matching_algorithm（可选）：“任意”、“全部”、“精确”、“正则表达式”、“模糊”中的一种
create_tag({
  name: "Invoice",
  color: "#ff0000",
  match: "invoice",
  matching_algorithm: "fuzzy"
})

通讯员操作

列表_对应者

召集所有通讯员。

list_correspondents()

create_对应

创建一个新的通讯员。

参数：

  • name:通讯员姓名
  • match（可选）：要匹配的文本模式
  • matching_algorithm（可选）：“任意”、“全部”、“精确”、“正则表达式”、“模糊”中的一种
create_correspondent({
  name: "ACME Corp",
  match: "ACME",
  matching_algorithm: "fuzzy"
})

文档类型操作

list_document_types

获取所有文档类型。

list_document_types()

create_document_type

创建新的文档类型。

参数：

  • name:文档类型名称
  • match（可选）：要匹配的文本模式
  • matching_algorithm（可选）：“任意”、“全部”、“精确”、“正则表达式”、“模糊”中的一种
create_document_type({
  name: "Invoice",
  match: "invoice total amount due",
  matching_algorithm: "any"
})

错误处理

在以下情况下，服务器将显示明确的错误消息：

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

发展

想要贡献或修改服务器吗？以下是你需要知道的：

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

服务器由以下组件构建：

  • 文学：用于构建MCP服务器的TypeScript框架
  • 黄道带：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）。此模式需要 快速 要安装（它作为依赖项包含在内）。

npm run start -- <baseUrl> <token> --http --port 3000
  • MCP API将在 POST /mcp 在指定的端口上。
  • 每个请求都是无状态处理的，遵循以下步骤 流式HTTP服务器传输 图案。
  • GET和DELETE请求 /mcp 将返回405 Method Not Allowed。

相关 MCP