Paperless-NGX MCP Server

无纸化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实例 1. 点击右上角的用户名 1. 选择“我的个人资料” 1. 单击圆形箭头按钮生成新令牌

1. 替换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 --  

2.HTTP（流式HTTP传输）

要将服务器作为HTTP服务运行，请使用 --http 旗帜。您还可以使用以下命令指定端口 --port （默认值：3000）。此模式需要 快速 要安装（它作为依赖项包含在内）。

npm run start --   --http --port 3000

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