Holded API协议服务器

MCP持有

用于保留API的模型上下文协议（MCP）服务器。该服务器允许像Claude这样的人工智能助手与Holded的发票、会计、联系人、产品、财务、人力资源、时间跟踪等进行交互。

由以下人员建造和维护 努比亚 -自动化和与商业人工智能（MCP、Holded、PipeDrive等）的集成。你想为你的公司做这样的事情吗？写信给我们 新闻.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访问权限的持有帐户
• 保留的API v2密钥(pat_… 或 sk_live_…)--生成它 抱住→ 设置→ 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（承载身份验证，游标分页）。您需要一个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

生成密钥 抱住→ 设置→ API.密钥必须以开头 pat_ 或 sk_live_A. 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桌面配置

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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…) 不再工作.在中生成v2密钥 抱住→ 设置→ API；密钥将以开头 pat_ 或 sk_live_.

设置为 HOLDED_API_KEY （或别名 HOLDED_API_KEY_V2).分开的 HOLDED_API_KEY_V2 1.x中用于选择加入HR/分类账/财务工具的变量不再需要——所有119个工具都始终已注册。

分页

列表工具从基于页面的分页更改为基于光标的分页：

现在，响应遵循以下信封：

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

通过传递进行迭代 nextCursor 作为 cursor 直到 hasMore 是 false.

响应格式

• 字段名称为 snake_case 整个（例如。 contact_id, created_at).
• 货币金额为 字符串 带有小数逗号（例如。 "1.234,56")--在进行算术运算之前，请使用支持区域设置的数字解析器进行解析。

删除或更改操作

联系人附件

附件现在由以下人员获取 文件名 而不是附件ID。使用 get_contact_attachment 随着 filename 字段返回 list_contact_attachments.

使用示例

配置后，您可以要求Claude：

文件

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

联系人

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

产品

• “显示所有产品”
• “创建一个名为Widget的新产品，价格为50欧元”
• “更新产品#123的库存，在仓库W1中增加10个单位”

人力资源与薪资

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

报告

• “得到我所有的税”
• “列出所有国库银行账户”
• “显示2025年1月的每日分类账”
• “获取会计科目表”

文档类型

API支持以下文档类型：

API 参考

基础网址

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

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

认证

所有请求都使用您的v2密钥进行承载身份验证：

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请求和响应都是实时传递的，以方便您的人工智能助手与Holded API之间的通信。

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

您的安全：我们建议以下安全最佳实践：将您的API密钥存储在环境变量中（永远不要将其提交到版本控制），定期更新到最新版本，并在您的AI助手中查看授予此MCP服务器的权限。有关更多信息，请参阅我们的 完整隐私政策.

支持

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

• GitHub问题: 报告问题
• 电子邮件[笑]hola@nubiia.es
• 文档: 持有API文件

关于努比亚

此MCP服务器由以下人员构建和维护 努比亚.

努比亚 帮助企业 自动化流程并将其工具与人工智能集成：定制MCP服务器，与 抱住，PipeDrive和其他ERP/CRM，以及将您的业务数据与Claude等与会者连接的代理。这 @nubiia/mcp-holded 这是我们所做的开源例子。

👉 您是否希望与人工智能集成或自动化以促进您的业务？ 新闻.es · ✉️ hola@nubiia.es

许可证

麻省理工学院-参见 许可证 文件以获取详细信息。

作者

由...建造 努比亚 — 新闻.es · hola@nubiia.es

维护者：塞缪尔·弗拉加-- GitHub · 领英

链接

• Nubia——人工智能自动化与集成
• 持有API文件
• MCP规范
• 隐私政策