mcp-holded

MCP Holded

适用于 Holded API 的模型上下文协议（MCP）服务。此服务可让 Claude 等 AI 助手与 Holded 的发票、会计、联系人、产品、资金管理、人力资源、工时追踪等功能交互。

由 Nubiia 构建并维护 — 为企业提供 AI 自动化与集成服务（MCP、Holded、Pipedrive 等）。想为您的企业打造类似方案？请通过 nubiia.es 联系我们。

功能

此 MCP 服务可访问 Holded API v2 中所有受支持的模块：

• 单据（16 个工具）：创建、列出、更新和删除发票、报价单、贷项通知单等。还可付款、发送、获取 PDF、发运商品等。
• 联系人（7 个工具）：管理客户和供应商及其附件。
• 产品（9 个工具）：全面管理产品，包括图片和库存。
• 资金管理（3 个工具）：管理旧版资金账户。
• 资金管理 v2（15 个工具）：银行账户、银行流水、现金流水、发票预测和对账。
• 费用账户（5 个工具）：管理费用账户类别。
• 编号系列（4 个工具）：配置单据编号。
• 销售渠道（5 个工具）：管理销售渠道。
• 仓库（6 个工具）：仓库管理。
• 付款（5 个工具）：付款方式配置。
• 税费（1 个工具）：获取可用税费。
• 联系人分组（5 个工具）：将联系人整理到分组中。
• 汇款（2 个工具）：访问汇款数据。
• 服务（5 个工具）：管理服务。
• 工时追踪（3 个工具）：列出工时追踪记录和项目工时（可读写）。
• 会计（2 个工具，只读）：获取会计科目表和日记账。
• 分类账（4 个工具）：列出和创建会计／分类账分录。
• 团队／人力资源（22 个工具）：员工管理、工资记录、员工工时记录和上下班打卡。

总计：119 个工具 — 配置有效的 v2 密钥后，所有工具都会无条件注册。

安装

前提条件

• Node.js 22.14 或更高版本
• 拥有 API 访问权限的 Holded 账户
• Holded API v2 密钥（pat_… 或 sk_live_…）— 在 Holded → Settings → API 中生成

从 npm 安装

npm install -g @nubiia/mcp-holded

从源代码安装

git clone https://github.com/nubiia-dev/mcp-holded.git
cd mcp-holded
npm install
npm run build

配置

环境变量

所有工具都会调用 Holded API v2（Bearer 身份验证、游标分页）。您只需要一个 v2 密钥：

# Recommended — primary key name
export HOLDED_API_KEY=pat_your_v2_key_here

# Alternative — accepted as an alias; wins over HOLDED_API_KEY if both are set
export HOLDED_API_KEY_V2=sk_live_your_v2_key_here

在 Holded → Settings → API 中生成密钥。密钥必须以 pat_ 或 sk_live_ 开头。403 响应表示密钥缺少必需的权限范围。

多租户设置请对每个租户使用相同逻辑：

export TENANT_1_NAME=company-a
export TENANT_1_API_KEY=pat_key_for_company_a
export TENANT_2_NAME=company-b
export TENANT_2_API_KEY=sk_live_key_for_company_b

TENANT_N_API_KEY_V2 可作为 TENANT_N_API_KEY 的别名使用（两者都设置时优先使用前者）。

Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-holded"],
      "env": {
        "HOLDED_API_KEY": "pat_your_v2_key_here"
      }
    }
  }
}

如果从源代码安装，也可以使用：

{
  "mcpServers": {
    "holded": {
      "command": "node",
      "args": ["/path/to/mcp-holded/dist/index.js"],
      "env": {
        "HOLDED_API_KEY": "pat_your_v2_key_here"
      }
    }
  }
}

从 1.x 迁移

API 密钥

服务器现在仅调用 Holded API v2。你的 1.x API 密钥（类似 abc123… 的纯十六进制字符串）已无法使用。请在 Holded → Settings → API 中生成 v2 密钥；密钥以 pat_ 或 sk_live_ 开头。

将其设为 HOLDED_API_KEY（或别名 HOLDED_API_KEY_V2）。1.x 中用于选择启用 HR/Ledger/Treasury 工具的独立变量 HOLDED_API_KEY_V2 已不再需要——119 个工具始终都会注册。

分页

列表工具已从基于页码的分页改为基于游标的分页：

1.x 参数	2.x 参数	说明
page	(已移除)	服务器不再接受偏移页码
pageSize	limit	由服务器分页；使用 limit 控制页面大小
(无)	cursor	传入上一次响应中的 nextCursor

响应现在采用以下封装格式：

{
  "items": [...],
  "nextCursor": "opaque-string-or-null",
  "hasMore": true
}

传入 nextCursor 作为 cursor，持续迭代，直到 hasMore 为 false。

响应格式

• 字段名统一使用 snake_case（例如 contact_id、created_at）。
• 金额是带小数逗号的字符串（例如 "1.234,56"）——进行算术运算前，请使用支持区域设置的数字解析器进行解析。

已移除或更改的操作

操作	1.x 行为	2.x 行为
purchaserefund 列出/获取/更新/删除/支付	支持	已移除——只能通过 /purchases/refund 创建
update_document 跟踪	所有文档类型	仅 salesorder 和 waybill
发货操作	所有文档类型	仅 salesorder 和 purchaseorder
实验性银行功能（reconcile_bank_transaction）	通过环境变量标志选择启用	已移除——请使用 reconcile_bank_movement（treasury v2）
get_daily_ledger 日期	Unix 时间戳（starttmp/endtmp）	ISO 8601 字符串（start_date/end_date）；为方便起见，仍接受旧版 Unix 参数
get_taxes	分页	一次调用返回所有税项（无分页参数）
update_product_stock	仓库可选	现在必须提供 warehouse_id
列表工具字段投影	默认字段集经过缩减	返回完整的 v2 负载；使用 fields 参数进行筛选

联系人附件

现在通过文件名而非附件 ID 获取附件。请将 list_contact_attachments 返回的 filename 字段传给 get_contact_attachment。

使用示例

配置完成后，你可以让 Claude：

文档

• “列出我在 Holded 中的所有发票”
• “为客户 X 创建一张包含 2 个项目的发票”
• “通过电子邮件向客户发送发票 #123”
• “获取发票 #456 的 PDF”
• “将发票 #789 标记为已付款”

联系人

• “列出我在 Holded 中的所有客户”
• “创建名为 Acme Corp 的新客户”
• “更新联系人 #123 的电子邮件地址”

产品

• “显示所有产品”
• “创建一个名为 Widget、价格为 50 EUR 的新产品”
• “为产品 #123 在仓库 W1 中增加 10 件库存”

HR 和薪资

• “列出所有员工”
• “为员工 #456 打卡上班”
• “获取员工 #789 在 2025 年 6 月的薪资记录”

报告

• “获取我的所有税项”
• “列出所有资金管理银行账户”
• “显示 2025 年 1 月的每日分类账”
• “获取会计科目表”

文档类型

该 API 支持以下文档类型：

类型	描述
invoice	销售发票
salesreceipt	销售收据
creditnote	贷项通知单（退款）
receiptnote	收款单
estimate	估价/报价
salesorder	销售订单
waybill	装箱单
proform	形式发票
purchase	采购
purchaserefund	采购退款（v2 中仅支持创建）
purchaseorder	采购订单

API 参考

基础 URL

https://api.holded.com/api/

服务器会将每个工具路由到相应的 v2 子路径（例如 /invoicing/v2/、/team/v2/、/accounting/v2/）。

身份验证

所有请求均使用你的 v2 密钥进行 Bearer 身份验证：

Authorization: Bearer pat_your_v2_key_here

分页

列表端点通过 limit 和 cursor 参数使用基于游标的分页（参见从 1.x 迁移）。

开发

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

写入安全

创建、更新和删除工具会修改 Holded 中的真实数据。服务会按工具应用速率限制（破坏性操作的限制更严格），以防意外进行批量修改。破坏性操作默认限制为每分钟 10 个请求；更新操作限制为每分钟 30 个请求。

隐私政策

数据收集：此 MCP 服务需要你的 Holded API 密钥才能运行。API 密钥从本地环境变量（HOLDED_API_KEY）中读取，此服务绝不会存储该密钥。所有 API 请求和响应都会实时传递，以便在 AI 助手与 Holded API 之间进行通信。

数据使用与共享：你的 API 密钥以及通过此服务处理的所有数据，仅用于代表你与 Holded API 交互。此服务充当直通代理——不会存储、记录或保留任何数据。你的 Holded API 密钥和数据只会传输到 Holded 的官方 API 端点（api.holded.com）。除 Holded 外，不会与任何第三方共享数据。

你的安全：我们建议遵循安全最佳实践：将 API 密钥存储在环境变量中（切勿将其提交到版本控制系统），定期更新到最新版本，并查看授予此 MCP 服务的 AI 助手权限。更多信息请参阅完整隐私政策。

支持

如有疑问、问题或功能请求：

• GitHub 问题：报告问题
• 电子邮件：[email protected]
• 文档：Holded API 文档

关于 Nubiia

此 MCP 服务由 Nubiia 构建并维护。

Nubiia 帮助企业自动化流程，并将工具与 AI 集成：量身定制的 MCP 服务、与 Holded、Pipedrive 及其他 ERP/CRM 的集成，以及将业务数据与 Claude 等助手连接起来的 Agent。这个 @nubiia/mcp-holded 是我们所做工作的一个开源示例。

👉 想为你的业务实现 AI 集成或自动化吗？nubiia.es · ✉️ [email protected]

许可证

MIT - 详情请参阅 LICENSE 文件。

作者

由 Nubiia 构建 — nubiia.es · [email protected]

维护者：Samuel Fraga — GitHub · LinkedIn

链接

• Nubiia — AI 自动化与集成
• Holded API 文档
• MCP 规范
• 隐私政策