持有MCP服务器

](https://www.npmjs.com/package/@energio/holded-mcp) ![License: MIT](LICENSE) ![CI](https://github.com/energio-es/holded-mcp/actions/workflows/ci.yml) ](package.json)

一种模型上下文协议（MCP）服务器，用于与保留的API集成。此服务器提供对Holded业务管理平台的全面访问，包括发票、会计、CRM、项目和团队功能。

特性

发票模块

文件：文档（发票、估算、采购等）的完整CRUD操作，以及付款、发送、PDF导出、跟踪和管道管理
联系人：联系人和联系人组的完整CRUD操作
产品：管理产品、变体和库存水平
支付：支付的完整CRUD操作
编号系列：文档编号系列的完整CRUD操作
财政部：创建、列出和检索金库/银行账户
支付方式：列出可用的付款方式
费用账户：费用账户的完整CRUD操作
销售渠道：销售渠道的完整CRUD操作
服务：服务的完整CRUD操作
税收：获取税务信息和税率
仓库：仓库的完整CRUD操作

CRM模块

潜在客户：创建、列出、获取、更新、删除潜在客户；管理阶段、笔记和任务
漏斗：针对具有自定义阶段的销售渠道的完整CRUD操作
事件：CRM事件的完整CRUD操作
预订：预订和管理地点的完整CRUD操作

项目模块

项目：项目的完整CRUD操作以及项目摘要
任务：项目任务的完整CRUD操作
时间追踪：项目时间跟踪条目的完整CRUD操作

会计模块

账户：使用基于前缀的编号列出并创建会计账户
每日分类账：列出每日分类账条目并创建会计条目

团队模块

员工：为员工提供完整的CRUD操作
时间追踪：列出所有时间跟踪，按员工列出，获取、创建、更新和删除时间跟踪条目

安装

先决条件

Node.js >=20（请与 node --version)
持有API密钥 -从以下地址获取您的保留的API设置或转到配置（顶部栏）→ API

快速入门（npx）

使用此MCP服务器的最简单方法是通过 npx -无需安装或构建！只需按如下所示配置您的MCP客户端。

Claude桌面设置

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

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

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

重新启动Claude Desktop以加载服务器。

Claude代码的设置

使用单个命令添加服务器：

claude mcp add holded -- npx -y @energio/holded-mcp

然后在您的环境中设置API密钥：

export HOLDED_API_KEY=your_api_key_here

光标设置

将以下内容添加到光标MCP设置文件中：

macOS: ~/.cursor/mcp.json
视窗: %APPDATA%\Cursor\mcp.json
Linux: ~/.config/cursor/mcp.json

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

保存后，重新启动Cursor或从设置中重新加载MCP服务器。

VS代码设置

将以下内容添加到您的VS Code用户设置中(settings.json)或工作区设置(.vscode/mcp.json):

用户设置(settings.json):

{
  "mcp": {
    "servers": {
      "holded": {
        "command": "npx",
        "args": ["-y", "@energio/holded-mcp"],
        "env": {
          "HOLDED_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

工作区设置(.vscode/mcp.json):

{
  "servers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "@energio/holded-mcp"],
      "env": {
        "HOLDED_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windsurf设置

将以下内容添加到Windsurf MCP配置文件中：

macOS: ~/.codeium/windsurf/mcp_config.json
视窗: %APPDATA%\Codeium\windsurf\mcp_config.json
Linux: ~/.codeium/windsurf/mcp_config.json

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

其他MCP兼容代理的设置

任何兼容MCP的代理都可以通过npx使用此服务器。一般配置要求：

命令: npx
参数: ["-y", "@energio/holded-mcp"]
环境变量: HOLDED_API_KEY 使用API密钥

配置示例：

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

服务器使用MCP协议通过stdio进行通信，可以与支持模型上下文协议.

配置

服务器需要 HOLDED_API_KEY 环境变量。这通常在MCP客户端配置中设置（请参阅上面的安装部分）。

对于手动/开发使用，您可以直接设置：

export HOLDED_API_KEY=your_api_key_here

模块选择

默认情况下，所有模块都已启用。要仅加载特定模块，请设置 HOLDED_MODULES 用逗号分隔的列表表示的环境变量：

可用模块: invoicing, crm, projects, accounting, team

示例-仅启用发票模块：

{
  "mcpServers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "@energio/holded-mcp"],
      "env": {
        "HOLDED_API_KEY": "your_api_key_here",
        "HOLDED_MODULES": "invoicing"
      }
    }
  }
}

配置示例:

所有模块（默认）：省略 HOLDED_MODULES 或者把它留空
只有CRM: "HOLDED_MODULES": "crm"
仅开具发票: "HOLDED_MODULES": "invoicing"
多个模块: "HOLDED_MODULES": "invoicing,crm"

调试模式

通过设置 HOLDED_DEBUG 环境变量：

{
  "mcpServers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "@energio/holded-mcp"],
      "env": {
        "HOLDED_API_KEY": "your_api_key_here",
        "HOLDED_DEBUG": "true"
      }
    }
  }
}

启用后，服务器会将重试尝试和API请求失败记录到stderr，这有助于解决连接问题或速率限制。

用法

手动运行服务器

npm start

或者用于自动重新加载的开发：

npm run dev

备注：在大多数情况下，您不会手动运行服务器。您的MCP客户端（Cursor、Claude Desktop等）将根据您的配置自动启动和管理服务器进程。

可用工具

联系工具

holded_invoicing_list_contacts -列出所有联系人
holded_invoicing_get_contact -获取特定联系人
holded_invoicing_create_contact -创建新联系人
holded_invoicing_update_contact -更新联系人
holded_invoicing_delete_contact -删除联系人
holded_invoicing_list_contact_groups -列出联系人组
holded_invoicing_get_contact_group -建立一个联络小组
holded_invoicing_create_contact_group -创建联系人组
holded_invoicing_update_contact_group -更新联系人组
holded_invoicing_delete_contact_group -删除联系人组
holded_invoicing_list_contact_attachments -列出联系人的附件
holded_invoicing_get_contact_attachment -获取特定的联系人附件

产品工具

holded_invoicing_list_products -列出所有产品
holded_invoicing_get_product -获取特定产品
holded_invoicing_create_product -创建新产品
holded_invoicing_update_product -更新产品
holded_invoicing_delete_product -删除产品
holded_invoicing_list_products_stock -列出特定仓库的产品库存水平
holded_invoicing_update_product_stock -更新产品库存
holded_invoicing_get_product_image -获取主要产品图片
holded_invoicing_list_product_images -列出所有产品图片
holded_invoicing_get_product_secondary_image -获取次要产品映像
holded_invoicing_upload_product_image -将图像上传到产品（接受 file_path 对于大文件； file_content base64仍然支持）

文档工具

holded_invoicing_list_documents -按类型列出文档
holded_invoicing_get_document -获取特定文档
holded_invoicing_create_document -创建新文档
holded_invoicing_update_document -更新文档
holded_invoicing_delete_document -删除文档
holded_invoicing_pay_document -记录文档的付款
holded_invoicing_send_document -通过电子邮件发送文档
holded_invoicing_get_document_pdf -获取文档的PDF版本
holded_invoicing_update_document_tracking -更新文档跟踪信息
holded_invoicing_update_document_pipeline -更新文档管道阶段
holded_invoicing_ship_all_items -从销售订单中发货所有商品
holded_invoicing_ship_items_by_line -从销售订单中按行运送特定商品
holded_invoicing_get_shipped_items -获取文档的已发货项目
holded_invoicing_attach_document_file -将文件附加到文档（接受 file_path 对于大文件； file_content base64仍然支持）

支付和财务工具

holded_invoicing_list_payments -列出所有付款
holded_invoicing_get_payment -获得特定付款
holded_invoicing_create_payment -创建付款
holded_invoicing_update_payment -更新付款
holded_invoicing_delete_payment -删除付款
holded_invoicing_get_numbering_series -按类型获取编号系列
holded_invoicing_create_numbering_serie -创建编号系列
holded_invoicing_update_numbering_serie -更新编号系列
holded_invoicing_delete_numbering_serie -删除编号系列
holded_invoicing_create_treasury -创建资金账户
holded_invoicing_list_treasuries -列出国库账户
holded_invoicing_get_treasury -开立国库账户
holded_invoicing_list_payment_methods -列出可用的付款方式

费用账户工具

holded_invoicing_list_expenses_accounts -列出所有费用账户
holded_invoicing_get_expenses_account -获取特定的费用账户
holded_invoicing_create_expenses_account -创建新的支出账户
holded_invoicing_update_expenses_account -更新费用账户
holded_invoicing_delete_expenses_account -删除费用账户

销售渠道工具

holded_invoicing_list_sales_channels -列出所有销售渠道
holded_invoicing_get_sales_channel -获得特定的销售渠道
holded_invoicing_create_sales_channel -创建新的销售渠道
holded_invoicing_update_sales_channel -更新销售渠道
holded_invoicing_delete_sales_channel -删除销售渠道

服务工具

holded_invoicing_list_services -列出所有服务
holded_invoicing_get_service -获取特定服务
holded_invoicing_create_service -创建新服务
holded_invoicing_update_service -更新服务
holded_invoicing_delete_service -删除服务

汇款工具

holded_invoicing_list_remittances -列出所有汇款
holded_invoicing_get_remittance -获取特定汇款

税务工具

holded_invoicing_get_taxes -获取所有税务信息

仓库工具

holded_invoicing_list_warehouses -列出所有仓库
holded_invoicing_get_warehouse -获取特定仓库
holded_invoicing_create_warehouse -创建新仓库
holded_invoicing_update_warehouse -更新仓库
holded_invoicing_delete_warehouse -删除仓库

CRM工具

铅工具

holded_crm_list_leads -列出所有潜在客户
holded_crm_get_lead -获取特定线索
holded_crm_create_lead -创建新的潜在客户
holded_crm_update_lead -更新潜在客户
holded_crm_delete_lead -删除潜在客户
holded_crm_update_lead_stage -将线索转移到另一个阶段
holded_crm_list_lead_notes -列出潜在客户的所有备注
holded_crm_create_lead_note -向潜在客户添加注释
holded_crm_update_lead_note -更新潜在客户说明
holded_crm_list_lead_tasks -列出潜在客户的所有任务
holded_crm_create_lead_task -为潜在客户创建任务
holded_crm_update_lead_task -更新潜在客户任务
holded_crm_delete_lead_task -删除潜在客户任务
holded_crm_update_lead_dates -更新交付日期

漏斗工具

holded_crm_list_funnels -列出所有漏斗
holded_crm_get_funnel -获取特定的漏斗
holded_crm_create_funnel -创建漏斗
holded_crm_update_funnel -更新漏斗
holded_crm_delete_funnel -删除漏斗

事件工具

holded_crm_list_events -列出所有事件
holded_crm_get_event -获取特定事件
holded_crm_create_event -创建事件
holded_crm_update_event -更新事件
holded_crm_delete_event -删除事件

预订工具

holded_crm_list_bookings -列出所有预订
holded_crm_get_booking -获取特定预订
holded_crm_create_booking -创建预订
holded_crm_update_booking -更新预订
holded_crm_delete_booking -删除/取消预订
holded_crm_list_booking_locations -列出预订地点
holded_crm_get_available_slots -获取可用的预订时段

项目工具

holded_projects_list_projects -列出所有项目
holded_projects_get_project -获取特定项目
holded_projects_create_project -创建项目
holded_projects_update_project -更新项目
holded_projects_delete_project -删除项目
holded_projects_get_project_summary -获取项目摘要/概述
holded_projects_list_tasks -列出所有任务
holded_projects_get_task -获取特定任务
holded_projects_create_task -创建任务
holded_projects_delete_task -删除任务

项目时间跟踪工具

holded_projects_list_project_time_trackings -列出项目的所有时间跟踪
holded_projects_get_project_time_tracking -获取特定项目时间跟踪条目
holded_projects_create_project_time_tracking -为项目创建时间跟踪条目
holded_projects_update_project_time_tracking -更新项目时间跟踪条目
holded_projects_delete_project_time_tracking -删除项目时间跟踪条目
holded_projects_list_all_times -列出所有项目的所有时间跟踪

会计工具

holded_accounting_list_accounts -列出所有会计科目（科目表/PGC科目）
holded_accounting_get_account -获取特定的会计账户
holded_accounting_create_account -创建会计帐户
holded_accounting_update_account -更新会计帐户
holded_accounting_delete_account -删除会计帐户
holded_accounting_list_daily_ledger -列出每日分类账条目
holded_accounting_create_entry -创建每日分类账条目

团队工具

员工工具

holded_team_list_employees -列出所有员工
holded_team_get_employee -找一个特定的员工
holded_team_create_employee -创建新员工
holded_team_update_employee -更新员工
holded_team_delete_employee -删除员工

时间跟踪工具

holded_team_list_all_time_trackings -列出所有员工的所有时间跟踪
holded_team_list_employee_time_trackings -列出特定员工的所有时间跟踪
holded_team_get_time_tracking -获取特定的时间跟踪条目
holded_team_create_employee_time_tracking -为员工创建时间跟踪条目
holded_team_update_time_tracking -更新时间跟踪条目
holded_team_delete_time_tracking -删除时间跟踪条目
holded_team_employee_clock_in -员工时钟
holded_team_employee_clock_out -给员工打卡
holded_team_employee_pause -暂停员工时间跟踪
holded_team_employee_unpause -暂停员工时间跟踪

文档类型

支持以下文档类型：

invoice -销售发票
salesreceipt -销售收据
creditnote -销售退款
receiptnote -门票销售退款
estimate -销售预估/报价
salesorder -销售订单
waybill -装箱单
proform -形式发票
purchase -购买
purchaserefund -购买退款
purchaseorder -采购订单

响应格式

所有工具都支持两种响应格式：

json （默认）-用于程序化处理的结构化JSON数据
markdown -人类可读的格式化文本

错误处理

服务器为常见场景提供清晰、可操作的错误消息：

身份验证错误（401）-检查您的API密钥
未找到错误（404）-验证资源ID
速率限制（429）-重试前请稍候
验证错误（422）-检查输入参数

演出

该服务器提供143个工具，涵盖所有Holded API模块。如果你只需要一部分功能，你可以通过使用 HOLDED_MODULES 环境变量（请参见模块选择以上）：

减少代币使用：更少的工具定义意味着发送给LLM的上下文更少
更快的响应：该模型在解析可用工具上花费的时间更少
降低成本：较小的提示降低了API基于令牌的计费成本

例如，如果您只处理发票，则可以设置 HOLDED_MODULES=invoicing 禁用CRM、项目、会计和团队模块。

故障排除

常见问题

1.找不到API密钥

错误: ERROR: HOLDED_API_KEY environment variable is required.

解决方案：确保在MCP客户端设置中正确配置了API密钥：

检查 HOLDED_API_KEY 设置在 env 部分
验证密钥是否正确（没有多余的空格或引号）
从配置获取API密钥→ 持有API

2.401未经授权

错误：API返回401状态代码

解决方案:

验证您的API密钥是否有效且未过期
检查密钥是否具有必要的权限
如果需要，重新生成API密钥

3.422验证错误

错误：API返回422状态代码

解决方案:

检查是否提供了所有必需的参数
验证参数类型是否符合预期（字符串与数字）
对于嵌套对象（库存更新、自定义字段），确保结构正确

4.模块未加载

错误：缺少特定模块中的工具

解决方案:

检查您是否已设置 HOLDED_MODULES 环境变量
如果设置了。， "HOLDED_MODULES": "invoicing,crm")
移除 HOLDED_MODULES 或者将其留空以加载所有模块

复杂操作示例

股票更新

更新产品库存需要一个嵌套的对象结构，您可以在其中指定仓库ID和产品/变体ID：

// Stock update structure: stock[warehouseId][productId/variantId] = quantity
{
  "product_id": "abc123",
  "stock": {
    "warehouse1": {
      "productId1": 100,
      "variantId1": 50
    },
    "warehouse2": {
      "productId1": 75
    }
  }
}

示例：将产品“abc123”的库存设置为仓库“wh1”中的100个单位：

{
  "product_id": "abc123",
  "stock": {
    "wh1": {
      "abc123": 100
    }
  }
}

预订创建

预订需要具有键值对的特定自定义字段：

{
  "locationId": "location123",
  "serviceId": "service456",
  "dateTime": 1730109600,  // Unix timestamp
  "timezone": "Europe/Madrid",
  "language": "es",
  "customFields": [
    {
      "key": "name",
      "value": "John Doe"
    },
    {
      "key": "email",
      "value": "john@example.com"
    },
    {
      "key": "phone",
      "value": "+34612345678"
    }
  ]
}

任务创建

任务需要项目ID和列表ID（项目中的列表/列）：

{
  "name": "New Task",
  "project_id": "proj123",
  "list_id": "list456"  // Get this from project details
}

备注：要获取可用的列表ID，请首先使用以下命令获取项目详细信息 holded_projects_get_project.

会计分录

每日分类账条目必须具有平衡的借方和贷方：

{
  "date": 1730109600,  // Unix timestamp
  "lines": [
    {
      "account": 4300,  // Account number (integer)
      "debit": 1000,
      "description": "Sales revenue"
    },
    {
      "account": 5700,  // Account number (integer)
      "credit": 1000,
      "description": "Bank account"
    }
  ],
  "notes": "Monthly sales entry"
}

需求:

最少2条线
借方总额必须等于贷方总额
每行必须有借方或贷方（不能同时有）
帐号必须为正整数

参数命名约定

此MCP服务器使用一致的参数命名约定：

路径/查询参数：使用 snake_case （例如。， employee_id, doc_type)
请求正文字段：使用 camelCase 匹配API（例如。， lastName, sendInvite)

工具处理程序自动将参数转换为Holded API所需的格式。

自定义字段

破解v1.4.0： 这 customFields 参数形状已更改 [{field, value}] 到公寓 {key: value} 对象。更换每个 [{field: "k", value: "v"}] 随着 {"k": "v"} 在电话中 create_document, update_document, update_lead，以及 update_funnel。响应使用相同的映射形状。Zod模式拒绝了旧的数组形状。

接受或退回的工具 customFields （文件、线索、漏斗）使用扁平 {key: value} 地图：

{
  "customFields": {
    "source_path": "/tmp/invoice.pdf",
    "source": "invoices-to-holded@v1/file"
  }
}

服务器将Holded的内部导线形状标准化（该形状因端点而异，并且在 POST /documents/{docType} --看 holded_api_specs/DRIFT.md#DRIFT-INV-14)因此，地图上的往返路线是一致的。在读取时，以前损坏的记录会被透明地修复。

记录API的怪癖

一些影响 create_document / update_document 呼叫者。工具描述包含了完整的规则——这是人类开发人员的交叉引用：

items[].subtotal 是单位价格，而不是线路总价。 Holded将其存储为 products[i].price 并计算 line_total = price × units.何时 units > 1，把这行字悄悄地递过书本上的文件。例子： {units: 40, subtotal: 100} （不是 subtotal: 4000)40小时×100欧元/小时。
items[].subtotal 意义是不对称的。 创建时，它以文档货币表示（Holded除以 currencyChange 存储欧元基数）。更新时，它是欧元基数本身（逐字存储）。重新传递从GET读取的值会保留状态；在更新时将发票货币值传递给账簿上的欧元总额。
currencyChange 是不可变的。 Holded PUT端点会自动删除该字段。要更改发票的汇率，请删除并重新创建新的 currencyChange 在创建时。这 update_document 模式拒绝该字段作为无法识别的键（破坏了v1.5.0中的更改）。
applyContactDefaults 覆盖行级帐户。 当 items[].accountingAccountId 已设置，您必须通过 applyContactDefaults: false。否则，联系人的默认帐户将自动获胜。这 create_document 模式强制执行了这一点（破坏了v1.5.0中的更改）。

工作流示例

本节演示了将多个API操作组合在一起的常见现实世界工作流。

创建完整发票

// 1. First, ensure you have a contact
const contact = await holded_invoicing_create_contact({
  name: "Acme Corp",
  email: "billing@acme.com",
  code: "B12345678"  // Tax ID
});

// 2. Create the invoice with line items
const invoice = await holded_invoicing_create_document({
  doc_type: "invoice",
  contactId: contact.id,
  contactName: "Acme Corp",
  date: 1730109600,  // Unix timestamp
  items: [
    {
      name: "Web Development Service",
      units: 40,
      subtotal: 100,  // per-unit: 40 hours × €100/hour → line total €4,000
      tax: 21  // 21% VAT
    },
    {
      name: "Hosting Service (Annual)",
      units: 1,
      subtotal: 500,  // per-unit; units == 1 so line total is also €500
      tax: 21
    }
  ],
  notes: "Payment due within 30 days"
});

// 3. Send the invoice via email
await holded_invoicing_send_document({
  doc_type: "invoice",
  document_id: invoice.id,
  emails: ["billing@acme.com"]
});

// 4. Record payment when received
await holded_invoicing_pay_document({
  doc_type: "invoice",
  document_id: invoice.id,
  paid: 5445,  // Total with VAT (€4,500 × 1.21)
  date: 1732701600  // Payment date
});

管理潜在客户生命周期

// 1. Create a new lead
const lead = await holded_crm_create_lead({
  name: "Enterprise Client Prospect",
  funnelId: "funnel123",
  stageId: "stage_initial_contact",
  contactName: "Jane Smith",
  email: "jane.smith@enterprise.com",
  phone: "+34912345678"
});

// 2. Add initial contact notes
await holded_crm_create_lead_note({
  lead_id: lead.id,
  note: "Initial call: Interested in enterprise plan. Budget: €50k/year. Decision timeline: Q2 2026."
});

// 3. Create follow-up task
await holded_crm_create_lead_task({
  lead_id: lead.id,
  task: "Send proposal and pricing",
  dueDate: 1730800000  // 1 week from now
});

// 4. Update lead stage after proposal sent
await holded_crm_update_lead_stage({
  lead_id: lead.id,
  stageId: "stage_proposal_sent"
});

// 5. Add proposal notes
await holded_crm_create_lead_note({
  lead_id: lead.id,
  note: "Sent proposal via email. Includes: Enterprise tier, custom integrations, dedicated support."
});

// 6. When deal is won, convert to contact
const contact = await holded_invoicing_create_contact({
  name: "Enterprise Client Inc",
  email: "jane.smith@enterprise.com",
  phone: "+34912345678"
});

// 7. Move lead to won stage
await holded_crm_update_lead_stage({
  lead_id: lead.id,
  stageId: "stage_won"
});

员工入职流程

// 1. Create new employee
const employee = await holded_team_create_employee({
  name: "María",
  lastName: "García",
  email: "maria.garcia@company.com",
  sendInvite: true  // Sends email invitation
});

// 2. Update employee details after onboarding
await holded_team_update_employee({
  employee_id: employee.id,
  phone: "+34666123456",
  mobile: "+34666123456",
  dateOfBirth: "15/03/1990",
  nationality: "Spanish",
  iban: "ES1234567890123456789012",
  address: {
    address: "Calle Mayor 123",
    city: "Madrid",
    postalCode: "28013",
    province: "Madrid",
    country: "Spain"
  },
  workplace: "office_madrid_001",
  teams: ["team_engineering", "team_backend"]
});

// 3. Set up first time tracking entry
await holded_team_create_employee_time_tracking({
  employee_id: employee.id,
  startTmp: "1730109600",  // 9:00 AM (Unix timestamp as string)
  endTmp: "1730138400"     // 5:00 PM (Unix timestamp as string)
});

// 4. Use clock-in/clock-out for daily tracking
await holded_team_employee_clock_in({
  employee_id: employee.id,
  location: "Madrid Office"
});

// Later in the day...
await holded_team_employee_clock_out({
  employee_id: employee.id,
  latitude: "40.4168",
  longitude: "-3.7038"
});

多仓库库存管理

// 1. Create warehouses
const warehouseMadrid = await holded_invoicing_create_warehouse({
  name: "Madrid Warehouse",
  address: {
    address: "Polígono Industrial Sur",
    city: "Madrid",
    postalCode: "28021",
    country: "Spain"
  }
});

const warehouseBarcelona = await holded_invoicing_create_warehouse({
  name: "Barcelona Warehouse",
  address: {
    address: "Zona Franca",
    city: "Barcelona",
    postalCode: "08040",
    country: "Spain"
  }
});

// 2. Create a product
const product = await holded_invoicing_create_product({
  name: "Wireless Mouse MX Master",
  sku: "TECH-MOUSE-001",
  price: 89.99,
  tax: 21
});

// 3. Update stock across multiple warehouses
await holded_invoicing_update_product_stock({
  product_id: product.id,
  stock: {
    [warehouseMadrid.id]: {
      [product.id]: 150  // 150 units in Madrid
    },
    [warehouseBarcelona.id]: {
      [product.id]: 200  // 200 units in Barcelona
    }
  }
});

// 4. Check stock levels for a specific warehouse
const madridStock = await holded_invoicing_list_products_stock({
  warehouse_id: warehouseMadrid.id
});

// 5. Transfer stock between warehouses (reduce Madrid, increase Barcelona)
await holded_invoicing_update_product_stock({
  product_id: product.id,
  stock: {
    [warehouseMadrid.id]: {
      [product.id]: 125  // Reduced by 25
    },
    [warehouseBarcelona.id]: {
      [product.id]: 225  // Increased by 25
    }
  }
});

文档传送工作流

// 1. Create a sales order
const salesOrder = await holded_invoicing_create_document({
  doc_type: "salesorder",
  contactId: "contact123",
  contactName: "Tech Store SL",
  date: 1730109600,
  items: [
    {
      name: "Laptop HP ProBook",
      sku: "LAPTOP-HP-001",
      units: 5,
      subtotal: 700,  // per-unit: €700 × 5 units → line total €3,500
      tax: 21
    },
    {
      name: "USB-C Dock",
      sku: "DOCK-USBC-001",
      units: 5,
      subtotal: 100,  // per-unit: €100 × 5 units → line total €500
      tax: 21
    }
  ],
  warehouseId: "warehouse_madrid_001"
});

// 2. Add tracking information
await holded_invoicing_update_document_tracking({
  doc_type: "salesorder",
  document_id: salesOrder.id,
  carrier: "DHL Express",
  trackingNumber: "1234567890",
  trackingUrl: "https://dhl.com/track/1234567890"
});

// 3. Ship all items at once
const shipment = await holded_invoicing_ship_all_items({
  document_id: salesOrder.id
});

// Alternative: Ship items line by line (partial shipments)
// await holded_invoicing_ship_items_by_line({
//   document_id: salesOrder.id,
//   lines: [
//     { lineId: "line1", units: 3 },  // Ship 3 laptops now
//     { lineId: "line2", units: 5 }   // Ship all docks now
//   ]
// });

// 4. Check shipped items
const shippedItems = await holded_invoicing_get_shipped_items({
  doc_type: "salesorder",
  document_id: salesOrder.id
});

// 5. Update pipeline stage
await holded_invoicing_update_document_pipeline({
  doc_type: "salesorder",
  document_id: salesOrder.id,
  pipelineStage: "shipped"
});

// 6. Create invoice from the sales order
const invoice = await holded_invoicing_create_document({
  doc_type: "invoice",
  contactId: "contact123",
  salesorderId: salesOrder.id,  // Link to sales order
  date: 1730196000
});

发展

从源代码构建

如果你想从源代码构建（用于开发或贡献）：

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

然后在MCP客户端配置中使用内置服务器：

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

开发命令

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode with auto-reload
npm run dev

# Clean build artifacts
npm run clean

贡献

欢迎投稿！请阅读我们的贡献指南有关提交pull请求过程的详细信息。

贡献者快速入门

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
进行更改
使用提交约定式提交 (git commit -m 'feat: add amazing feature')
推到您的分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

社区与治理

支持

持有API文件: https://developers.holded.com/reference
问题: - *响应时间：1-2周*
讨论:
安全: 报告漏洞 - *响应时间：72小时*

Holded MCP

快速接入

详细介绍

持有MCP服务器

目录

特性

发票模块

CRM模块

项目模块

会计模块

团队模块

安装

先决条件

快速入门（npx）

Claude桌面设置

Claude代码的设置

光标设置

VS代码设置

Windsurf设置

其他MCP兼容代理的设置

配置

模块选择

调试模式

用法

手动运行服务器

可用工具

联系工具

产品工具

文档工具

支付和财务工具

费用账户工具

销售渠道工具

服务工具

汇款工具

税务工具

仓库工具

CRM工具

铅工具

漏斗工具

事件工具

预订工具

项目工具

项目时间跟踪工具

会计工具

团队工具

员工工具

时间跟踪工具

文档类型

响应格式

错误处理

演出

故障排除

常见问题

1.找不到API密钥

2.401未经授权

3.422验证错误

4.模块未加载

复杂操作示例

股票更新

预订创建

任务创建

会计分录

参数命名约定

自定义字段

记录API的怪癖

工作流示例

创建完整发票

管理潜在客户生命周期

员工入职流程

多仓库库存管理

文档传送工作流

发展

从源代码构建

开发命令

贡献

贡献者快速入门

许可证

社区与治理

支持

目录标签