@菲菲/胡利mcp

](https://www.npmjs.com/package/@firfi/huly-mcp) ](https://www.npmjs.com/package/@firfi/huly-mcp) ![License: MIT](https://opensource.org/licenses/MIT) ![MCP](https://modelcontextprotocol.io) ![TypeScript](https://www.typescriptlang.org/)

MCP服务器胡莉整合。

安装

标准配置适用于大多数MCP客户端：

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Claude Code

claude mcp add huly \
  -e HULY_URL=https://huly.app \
  -e HULY_EMAIL=your@email.com \
  -e HULY_PASSWORD=yourpassword \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest

或添加到 ~/.claude.json 使用上面的标准配置。

Claude Desktop

将标准配置添加到您的 claude_desktop_config.json:

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

VS Code

添加到您的用户设置(.vscode/mcp.json)或使用命令面板→ “MCP:添加服务器”：

{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Cursor

将标准配置添加到 ~/.cursor/mcp.json，或通过设置→ 工具和集成→ 新的MCP服务器。

Windsurf

将标准配置添加到Windsurf MCP配置文件中。

OpenCode

打开全局配置文件(~/.config/opencode/opencode.json)并将此配置添加到 mcp 部分。

"huly": {
      "type": "local",
      "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
      "environment": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }

更新

这 @latest install命令中的标签总是获取最新版本。大多数MCP客户端都会缓存已安装的包，因此您需要强制重新获取：

客户端	如何更新
克劳德代码	`claude mcp remove huly` 然后使用上面的install命令重新添加
克劳德桌面版	重新启动应用程序（它正在运行 `npx` 启动时）
VS代码/光标	从命令面板重新启动MCP服务器或重新加载窗口
npx（手动）	`npx -y @firfi/huly-mcp@latest` --the `-y` 标志在以下情况下跳过缓存 `@latest` 解析为新版本

HTTP传输

默认情况下，服务器使用stdio传输。对于HTTP传输（流式HTTP）：

HULY_URL=https://huly.app \
HULY_EMAIL=your@email.com \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @firfi/huly-mcp@latest

服务器正在监听 http://127.0.0.1:3000/mcp 默认情况下。

配置为 MCP_HTTP_PORT 和 MCP_HTTP_HOST:

MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-mcp@latest

环境变量

变量	必填	描述
`HULY_URL`	是	Huly实例URL
`HULY_EMAIL`	身份验证\*	帐户电子邮件
`HULY_PASSWORD`	身份验证\*	帐户密码
`HULY_TOKEN`	Auth\*	neneneba API令牌（替代电子邮件/密码）
`HULY_WORKSPACE`	是	工作区标识符
`HULY_CONNECTION_TIMEOUT`	否	连接超时（毫秒）（默认值：30000）
`MCP_TRANSPORT`	否	运输类型： `stdio` （默认）或 `http`
`MCP_HTTP_PORT`	否	HTTP服务器端口（默认值：3000）
`MCP_HTTP_HOST`	否	HTTP服务器主机（默认值：127.0.0.1）
`TOOLSETS`	没有	要公开的逗号分隔的工具类别。如果未设置，所有工具都会暴露出来。例子： `issues,projects,search`

\*认证：提供其中之一 HULY_EMAIL + HULY_PASSWORD 或 HULY_TOKEN.

可用工具

TOOLSETS 类别： projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendar, time tracking, search, activity, notifications, workspace, cards, custom-fields, labels, leads, tag-categories, task-management, test-management

项目

工具	说明
`list_projects`	列出所有Huly项目。返回按名称排序的项目。支持按存档状态进行筛选。
`get_project`	获取Huly项目的完整详细信息，包括其状态。返回项目名称、描述、存档标志、默认状态和所有可用状态。
`list_statuses`	列出带有类别信息的Huly项目的所有问题状态。返回状态名称、isDone、isCanceled和isDefault标志。使用此功能在创建或更新问题之前发现有效状态。
`create_project`	创建一个新的Huly跟踪器项目。Idempotent：如果具有相同标识符的项目已经存在（created=false），则返回现有项目。标识符必须是以字母开头的1-5个大写字母数字字符。
`update_project`	更新Huly项目。仅修改提供的字段。将描述设置为null以将其清除
`delete_project`	永久删除Huly项目。此项目中的所有问题、里程碑和组件都将成为孤立的。此操作无法撤消。

问题

工具	说明
`preview_deletion`	在实际删除Huly实体之前预览删除它的影响。显示受影响的子实体、关系和警告。支持问题、项目、组件和里程碑。在调用删除操作之前，使用此方法了解级联效应。
`list_issues`	查询Huly的可选过滤器问题。返回按修改日期排序的问题（最新问题排在第一位）。支持按项目、状态、受让人、组件和parentIssue进行筛选（列出特定问题的子问题）。支持按标题子字符串（titleSearch）和描述内容（descriptionSearch）进行搜索。
`get_issue`	检索Huly问题的完整详细信息，包括降价描述。使用此功能可查看问题内容、评论或完整元数据。
`create_issue`	在Huly项目中创建新问题。通过指定parentIssue作为子问题创建（可选）。描述支持markdown格式。返回创建的问题标识符。
`update_issue`	更新现有Huly问题的字段。仅修改提供的字段。描述更新支持markdown。
`add_issue_label`	为Huly问题添加标签。如果项目中不存在标记，则创建标记。
`remove_issue_label`	从Huly问题中删除标签。分离标签引用；不会删除标签定义。
`delete_issue`	永久删除Huly问题。此操作无法撤消。
`move_issue`	将问题移动到新的父级（使其成为子问题）或顶级（null）。更新父/子关系和子问题计数。
`list_components`	列出Huly项目中的组件。组件按区域/特征组织问题。返回按修改日期排序的组件（最新的第一个）。
`get_component`	检索Huly组件的完整详细信息。使用此功能查看组件内容和元数据。
`create_component`	在Huly项目中创建新组件。组件有助于按区域/特征组织问题。返回创建的组件ID和标签。
`update_component`	更新现有Huly组件上的字段。仅修改提供的字段。
`set_issue_component`	设置或清除Huly问题上的组件。为组件传递null以清除它
`delete_component`	永久删除Huly组件。此操作无法撤消。
`list_issue_templates`	列出Huly项目中的问题模板。模板定义了可重用的问题配置。返回按修改日期排序的模板（最新的优先）。
`get_issue_template`	检索Huly问题模板（包括子任务模板）的完整详细信息。使用此选项可以查看模板内容、默认值和子模板ID。
`create_issue_template`	在Huly项目中创建新的问题模板。模板为新问题定义默认值。（可选）包含子项（子任务模板），在从此模板创建问题时，这些子项将成为子问题。返回创建的模板ID和标题。
`create_issue_from_template`	从模板创建新问题。应用模板默认值，允许覆盖特定字段。如果模板有子项（子任务模板），则会自动创建子问题，除非includeChildren设置为false。返回创建的问题标识符和创建的子项计数。
`update_issue_template`	更新现有Huly问题模板上的字段。仅修改提供的字段。
`delete_issue_template`	永久删除Huly问题模板。此操作无法撤消。
`add_template_child`	将子（子任务）模板添加到问题模板中。子问题定义了使用create_issue_from_template时创建的子问题的默认值。返回子模板ID
`remove_template_child`	按子ID从问题模板中删除子（子任务）模板。从Get_issue_template响应中获取子ID。
`add_issue_relation`	添加两个问题之间的关系。关系类型：“块”（源块-目标-推入目标的blockedBy），“被阻塞”（源被目标阻塞-推入源的blockedBy），“关联”（双向链接-更新双方）。targetIssue接受跨项目标识符，如“OTHER-42”。如果关系已存在，则无操作。
`remove_issue_relation`	删除两个问题之间的关系。镜像add_issue_relationship：“阻止”从目标的blockedBy拉取，“被阻止”从源的blockedBy拉取，与“从两侧拉取”相关。如果关系不存在，则不执行操作。
`list_issue_relations`	列出问题的所有关系。返回blockedBy（阻塞此问题的问题）、关系（双向问题链接）和文档（带有标题/团队空间的链接文档）。不返回此问题阻止的问题——在目标问题上使用list_issue_relations来查看。
`link_document_to_issue`	将Huly文档链接到问题。该链接出现在UI中问题的“关系”面板中。Idempotent：如果文档已链接，则无操作。使用list_issue_relations查看链接的文档。
`unlink_document_from_issue`	从问题中删除文档链接。Idempotent：如果文档未链接，则无操作。

工具	说明
`list_comments`	列出对Huly问题的评论。返回按创建日期排序的注释（最早的第一个）。
`add_comment`	为Huly问题添加评论。注释正文支持markdown格式。
`update_comment`	更新关于Huly问题的现有评论。注释正文支持markdown格式。
`delete_comment`	从Huly问题中删除评论。此操作无法撤消。

里程碑

工具	说明
`list_milestones`	列出Huly项目中的里程碑。返回按修改日期排序的里程碑（最新的第一个）。
`get_milestone`	检索Huly里程碑的完整详细信息。使用此功能查看里程碑内容和元数据。
`create_milestone`	在Huly项目中创建一个新的里程碑。返回创建的里程碑ID和标签。
`update_milestone`	更新现有Huly里程碑上的字段。仅修改提供的字段。
`set_issue_milestone`	设置或清除Huly问题的里程碑。为里程碑传递null以将其清除
`delete_milestone`	永久删除Huly里程碑。此操作无法撤消。

文件

工具	说明
`list_teamspaces`	列出所有Huly文档团队空间。返回按名称排序的团队空间。支持按存档状态进行筛选。
`get_teamspace`	获取Huly文档团队空间的详细信息，包括文档计数。按名称或ID查找，包括存档的团队空间。
`create_teamspace`	创建新的Huly文档团队空间。Idempotent：如果存在同名团队空间，则返回现有团队空间。
`update_teamspace`	更新现有Huly文档团队空间上的字段。仅修改提供的字段。将描述设置为null以将其清除
`delete_teamspace`	永久删除Huly文档团队空间。此操作无法撤消。
`list_documents`	列出Huly团队空间中的文档。返回按修改日期排序的文档（最新的第一个）。每个结果都包含一个指向Huly web应用程序中文档的“url”字段。支持按标题子字符串（titleSearch）和内容（contentSearch）进行搜索。
`get_document`	在Huly web应用程序中检索Huly文档的完整详细信息，包括标记内容和指向该文档的“url”字段。使用此功能查看文档内容和元数据。
`create_document`	在Huly团队空间中创建新文档。内容支持完整的标记，包括原生美人鱼图（“”美人鱼块在Huly UI中交互式渲染）。可选地将父级作为文档标题或ID传递，以创建嵌套的子文档；无效的父级会失败，而不是默默地创建顶级文档。返回创建的文档id和指向Huly web应用程序中文档的“url”字段。使用link_document_to_oissue将文档与跟踪问题相关联。
`edit_document`	编辑现有的Huly文档。两种内容模式（互斥）：（1）“content”用于完全替换，（2）“old_text”+“new_text”用于目标搜索和替换。除非replace_all为真，否则多个匹配错误。空的new_text会删除匹配的文本。还支持通过“title”重命名。内容支持完整的markdown，包括原生Mermaid图。返回一个指向Huly web应用程序中文档的“url”字段。
`list_inline_comments`	列出Huly文档中的内联注释线程。提取文档内容中嵌入的注释作为ProseMirror标记。每条评论都包含突出显示的文本和线程ID。设置includeReplies=true也可以获取带有发件人姓名的线程回复消息。
`delete_document`	永久删除Huly文档。此操作无法撤消。

存储

工具	说明
`upload_file`	将文件上传到Huly存储。提供以下选项之一：filePath（本地文件-首选）、fileUrl（从URL获取）或data（base64-仅适用于小文件）。返回用于引用文件的blob ID和URL。

附件

工具	说明
`list_attachments`	列出Huly对象（问题、文档等）上的附件。返回按修改日期排序的附件（最新的第一个）。
`get_attachment`	检索Huly附件的完整详细信息，包括下载URL
`add_attachment`	向Huly对象添加附件。请提供以下选项之一：filePath（首选本地文件）、fileUrl（从URL获取）或data（base64）。返回附件ID和下载URL
`update_attachment`	更新附件元数据（描述、固定状态）。
`delete_attachment`	永久删除附件。此操作无法撤消。
`pin_attachment`	固定或取消固定附件。
`download_attachment`	获取附件的下载URL以及文件元数据（名称、类型、大小）。
`add_issue_attachment`	为Huly问题添加附件。按项目和标识符查找问题的便利方法。请提供以下选项之一：filePath、fileUrl或数据。
`add_document_attachment`	向Huly文档添加附件。按团队空间和标题/ID查找文档的便利方法。请提供以下之一：filePath、fileUrl或data。

联系人

工具	说明
`list_persons`	列出Huly工作区中的所有人员。返回按修改日期排序的人员（最新者优先）。支持按名称子字符串（nameSearch）和电子邮件子字符串（emailSearch）搜索。
`get_person`	检索人员的完整详细信息，包括联系渠道。使用personId或电子邮件来识别该人。
`create_person`	在Huly中创建一个新用户。返回创建的人员ID
`update_person`	更新现有人员的字段。仅修改提供的字段。
`delete_person`	从Huly中永久删除一个人。此操作无法撤消。
`list_employees`	列出员工（团队成员）。返回按修改日期排序的员工（最新员工优先）。
`list_organizations`	列出Huly工作区中的所有组织。返回按修改日期排序的组织（最新的第一个）。
`create_organization`	在Huly创建一个新组织。可选择按个人ID或电子邮件添加成员。如果无法解析任何请求的成员，则失败。返回创建的组织ID
`get_organization`	当名称唯一时，通过ID或确切名称检索组织的完整详细信息，包括城市、描述、成员计数和修改时间戳。如果多个组织共享同一名称，请使用组织ID
`update_organization`	当名称唯一时，更新由ID或确切名称标识的现有组织上的字段。仅修改提供的字段。描述支持多行纯文本，是存储CRM笔记/收入摘要/上下文的正确位置。传递null以清除城市或描述。如果多个组织共享同一名称，请使用组织ID
`delete_organization`	当名称唯一时，永久删除由ID或确切名称标识的组织。小心使用-这是无法撤消的。可用于在将数据合并到其他位置后清理重复的组织。如果多个组织共享同一名称，请使用组织ID
`make_organization_customer`	将Customer混入应用于组织，使其显示在Huly Leads>Customers视图中。Idempotent-可以安全地致电已经是客户的组织。如果组织ID或确切名称是唯一的，则采用该名称。
`add_organization_channel`	将联系渠道（电话、电子邮件、网站/主页、领英、推特、GitHub、脸书、电报）添加到由ID或确切唯一名称标识的组织中。提供商名称：电子邮件、电话、领英、推特、github、脸书、电报、主页。
`add_organization_member`	将某人链接为组织成员。该人出现在Huly中该组织的“成员”选项卡下。使用个人ID或电子邮件来识别该人。Idempotent：如果该人已经是成员，则返回added=false。
`list_organization_members`	列出一个组织的所有成员。返回每个成员的个人ID、姓名和主要电子邮件（如果有的话）。当使用名称而不是ID时，该名称必须恰好标识一个组织。
`list_person_organizations`	列出一个人所属的所有组织。提供个人ID或电子邮件。返回每个组织的ID和名称。
`remove_organization_member`	取消一个人与组织成员的链接。反转add_organization_member。返回已删除：如果该人不是成员，则返回false。当使用组织名称而不是ID时，该名称必须恰好标识一个组织。

频道

工具	说明
`list_channels`	列出所有Huly频道。返回按名称排序的频道。支持按存档状态进行筛选。支持按名称子字符串（nameSearch）和主题子字符串（topicSearch）搜索。
`get_channel`	检索Huly频道的完整详细信息，包括主题和成员列表。
`create_channel`	在Huly中创建一个新频道。返回创建的通道ID和名称。
`update_channel`	更新现有Huly频道上的字段。仅修改提供的字段。
`delete_channel`	永久删除Huly频道。此操作无法撤消。
`list_channel_messages`	在Huly频道中列出消息。返回按日期排序的邮件（最新的第一个）。
`send_channel_message`	向Huly频道发送消息。邮件正文支持markdown格式。
`update_channel_message`	更新频道消息。只有身体可以修改。
`delete_channel_message`	永久删除频道消息。此操作无法撤消。
`list_direct_messages`	列出Huly中的直接消息对话。返回按日期排序的对话（最新的优先）。
`create_direct_message`	与工作区成员打开一对一的直接消息对话。这 `person` 参数接受电子邮件或确切的显示名称（例如。 `Smith,Bill`).Idempotent：如果具有该参与者的DM已经存在，则返回它(`created: false`)；否则创建新的DM(`created: true`).回归 `id` 可以传递为 `dm` 发送dm_message、列出dmmessage等。
`list_dm_messages`	在直接消息对话中列出消息，最新消息优先。这 `dm` 参数接受DM `_id` 或参与者显示名称（例如。 `Kerr,Shannon`)；名称仅解析为具有经过身份验证的帐户的一对一DM。
`send_dm_message`	向直接消息对话发送消息。这 `dm` 参数接受DM `_id` 或参与者显示名称；名称仅解析为具有经过身份验证的帐户的一对一DM。邮件正文支持markdown格式。
`update_dm_message`	更新直接消息。这 `dm` 参数接受DM `_id` 或参与者显示名称；名称仅解析为具有经过身份验证的帐户的一对一DM。只有身体可以修改。
`delete_dm_message`	永久删除直接消息。这 `dm` 参数接受DM `_id` 或参与者显示名称；名称仅解析为具有经过身份验证的帐户的一对一DM。此操作无法撤消。
`list_thread_replies`	在消息线程中列出回复。返回按日期排序的答复（最早的先到）。
`add_thread_reply`	向消息线程添加回复。回复正文支持markdown格式。
`update_thread_reply`	更新线程回复。只有身体可以修改。
`delete_thread_reply`	永久删除帖子回复。此操作无法撤消。

日历

工具	说明
`list_events`	列出日历事件。返回按日期排序的事件。支持按日期范围过滤。
`list_calendars`	列出可用作create_event或create_recuring_event目标的可写、非隐藏日历。当您需要显式选择目标calendarId时，请在创建事件之前使用此选项。
`get_event`	检索日历事件的完整详细信息，包括描述。使用此功能查看事件内容和元数据。
`create_event`	创建新的日历事件。描述支持markdown格式。可选的calendarId针对特定的日历；如果省略，事件将使用经过身份验证的用户的主要个人日历。返回创建的事件ID
`update_event`	更新现有日历事件上的字段。仅修改提供的字段。描述更新支持markdown。
`delete_event`	永久删除日历事件。此操作无法撤消。
`list_recurring_events`	列出重复事件定义。返回按修改日期排序的重复事件（最新事件排在第一位）。
`create_recurring_event`	使用RFC5545 RRULE规则创建新的定期日历事件。描述支持markdown。可选的calendarId针对特定的日历；如果省略，事件将使用经过身份验证的用户的主要个人日历。返回创建的事件ID
`list_event_instances`	列出重复事件的实例。返回按日期排序的实例。支持按日期范围过滤。使用includeParticipans=true获取完整的参与者信息（额外查找）。

时间追踪

工具	说明
`log_time`	记录在Huly问题上花费的时间。记录带有可选描述的时间条目。时间值以分钟为单位。
`get_time_report`	获取特定Huly问题的时间跟踪报告。显示总时间、估计值、剩余时间和所有时间条目。
`list_time_spend_reports`	列出跨问题的所有时间条目。支持按项目和日期范围过滤。返回按日期排序的条目（最新的第一个）。
`get_detailed_time_report`	获取项目的详细时间分解。显示按问题和员工分组的总时间。支持日期范围过滤
`list_work_slots`	列出计划的工作时段。显示附加到ToDos的计划时间块。支持按员工和日期范围过滤。
`create_work_slot`	创建一个计划的工作时段。出于规划目的，将时间块附加到待办事项。
`start_timer`	在Huly问题上启动客户端计时器。验证问题是否存在并返回开始时间戳。使用log_time记录完成时经过的时间。
`stop_timer`	在Huly问题上停止客户端计时器。返回停止时间戳。从开始/停止时间戳计算经过的时间，并使用log_time进行记录

搜索

工具	说明
`fulltext_search`	在所有Huly内容中执行全局全文搜索。搜索问题、文档、消息和其他索引内容。返回按相关性排序的匹配项（最新项优先）。

活动

工具	说明
`list_activity`	列出Huly对象的活动消息。返回按日期排序的活动（最新的优先）。
`add_reaction`	在活动消息中添加表情符号反应。
`remove_reaction`	从活动消息中删除表情符号反应。
`list_reactions`	列出活动消息上的反应。
`save_message`	保存/标记活动消息以供以后参考。
`unsave_message`	从已保存/书签中删除活动消息。
`list_saved_messages`	列出已保存/已添加书签的活动消息。
`list_mentions`	在活动消息中列出当前用户的@提及。

通知

工具	说明
`list_notifications`	列出收件箱通知。返回按修改日期排序的通知（最新的优先）。支持按读取/存档状态进行过滤。
`get_notification`	检索通知的完整详细信息。使用此选项可查看通知内容和元数据。
`mark_notification_read`	将通知标记为已读。
`mark_all_notifications_read`	将所有未读通知标记为已读。返回标记的通知计数。
`archive_notification`	将通知存档。存档的通知在主收件箱视图中隐藏。
`archive_all_notifications`	将所有通知存档。返回存档的通知计数。
`delete_notification`	永久删除通知。此操作无法撤消。
`get_notification_context`	获取实体的通知上下文。返回特定对象的跟踪信息。
`list_notification_contexts`	列出通知上下文。返回按上次更新时间戳排序的上下文（最新优先）。支持按固定状态过滤。
`pin_notification_context`	固定或取消固定通知上下文。收件箱中突出显示固定上下文。
`list_notification_settings`	列出通知提供程序设置。返回当前通知首选项。
`update_notification_provider_setting`	更新通知提供程序设置。启用或禁用特定提供程序的通知。
`get_unread_notification_count`	获取未读通知的计数。

工作区

工具	说明
`list_workspace_members`	列出当前Huly工作区中的成员及其角色。返回具有帐户ID和角色的成员。
`update_member_role`	更新工作区成员的角色。需要适当的权限。有效角色：只读用户、DocGuest、访客、用户、维护者、所有者、管理员。
`get_workspace_info`	获取有关当前工作区的信息，包括名称、URL、区域和设置。
`list_workspaces`	列出当前用户可访问的所有工作区。返回按上次访问排序的工作区摘要。
`create_workspace`	创建新的Huly工作区。返回工作区UUID和URL。可选地指定一个区域。
`delete_workspace`	永久删除当前工作区。此操作无法撤消。请务必谨慎使用。
`get_user_profile`	获取当前用户的个人资料信息，包括个人信息、位置和社交链接。
`update_user_profile`	更新当前用户的个人资料。支持生物、城市、国家、网站、社交链接和公众可见性。
`update_guest_settings`	更新工作区访客设置。控制只读访客访问和访客注册权限。
`create_access_link`	创建Huly工作区访问链接。默认为GUEST角色。通过使用notBefore和expiration设置personalize=false来支持匿名可重用访客链接，并可以通过空格限制对特定Huly空间ID的访问。
`get_regions`	获取创建工作区的可用区域。返回地区代码和显示名称。

卡片

工具	说明
`list_card_spaces`	列出所有Huly卡空间。返回按名称排序的卡片空间。卡片空间是卡片的容器。
`list_master_tags`	列出Huly卡空间中可用的主标签（卡类型）。主标签定义了可以在空间中创建的卡的类型/模式。
`list_cards`	在Huly卡片空间中列出卡片。返回按修改日期排序的卡片（最新的第一个）。支持按类型（主标记）、标题子字符串和内容搜索进行过滤。
`get_card`	检索Huly卡的完整详细信息，包括降价内容。使用此功能查看卡片内容和元数据。
`create_card`	在Huly卡空间中创建新卡。需要主标签（卡片类型）。内容支持markdown格式。返回创建的卡id
`update_card`	更新现有Huly卡上的字段。仅修改提供的字段。内容更新支持markdown。
`delete_card`	永久删除Huly卡。此操作无法撤消。

自定义字段

工具	说明
`list_custom_fields`	列出工作区中的自定义字段定义。返回字段及其标签、类型和所有者类信息。自定义字段是在Huly UI中针对卡类型、问题类型或其他类创建的。使用targetClass筛选特定类的字段。
`get_custom_field_values`	从文档中读取自定义字段值。传递文档的ID和类（来自list_cards、list_issues等）。返回文档上找到的所有自定义字段值及其标签和类型。
`set_custom_field`	在文档上设置自定义字段值。需要文档ID、类、字段ID（来自list_custom_fields）和值。值是自动解析的：数字来自数字字符串，布尔值来自“true”/“false”，字符串按原样

工具	说明
`list_labels`	列出工作区中的标签/标记定义。标签是全局的（不是项目范围的）。返回按修改日期排序的跟踪器问题标签（最新的第一个）。
`create_label`	在工作区中创建新的标签/标记定义。标签是全球性的，可以附加到任何问题上。如果已存在具有相同标题的标签（created=false），则返回现有标签。使用add_issue_label为特定问题附加标签。
`update_label`	更新标签/标记定义。接受标签ID或标题。仅修改提供的字段。
`delete_label`	永久删除标签/标记定义。接受标签ID或标题。此操作无法撤消。

潜在客户

工具	说明
`list_funnels`	列出所有Huly销售渠道（主要渠道）。返回每个漏斗的稳定ID和显示名称，按名称排序。支持按存档状态进行筛选。
`list_leads`	Query Huly在带有可选过滤器的漏斗中领先。传递list_funnels返回的漏斗ID，或漏斗名称以方便查找。返回按修改日期排序的潜在客户（最新的优先）。支持按状态、受让人和标题搜索进行筛选。
`get_lead`	检索Huly潜在客户的完整详细信息，包括降价描述、客户名称、渠道ID和渠道名称以及状态。线索标识符遵循上游的Huly格式，如“Lead-1”。

标签类别

工具	说明
`list_tag_categories`	列出工作区中的标记/标签类别。类别组标签（例如，“优先级标签”、“类型标签”）。可选targetClass筛选器（默认为全部）。
`create_tag_category`	创建新的标记/标签类别。Idempotent：如果具有相同标签和targetClass的类别已经存在（created=false），则返回现有类别。将targetClass默认为跟踪器问题。
`update_tag_category`	更新标签/标签类别。接受类别ID或标签名称。仅修改提供的字段。
`delete_tag_category`	永久删除标记/标签类别。接受类别ID或标签名称。此类别中的标签将成为孤立标签（不删除）。此操作无法撤消。

任务管理

工具	说明
`list_project_types`	列出Huly跟踪器项目类型/工作流模板。返回ID、显示名称、描述符、任务类型计数、状态计数，以及该类型是否显示为默认的经典跟踪器类型。
`get_project_type`	在一次通话中检查一个Huly跟踪器项目类型。接受projectType作为ID或显示名称；如果省略，则使用明确的经典跟踪器类型。返回任务类型、状态、类别和任务类型到状态的映射。
`list_task_types`	列出Huly问题/任务类型。可选择按项目类型ID或显示名称进行筛选。返回任务类型标识、父项目类型、类型、问题类和可用状态计数。
`create_task_type`	通过规范化名称将Huly问题/任务类型等效地添加到项目类型中。从现有模板任务类型复制所需的工作流配置，除非提供了templateTaskType。返回已创建的ID、受影响的任务类型ID和工作区级工作流警告。
`create_issue_status`	在项目类型和任务类型范围内，按规范化名称等效地添加Huly问题工作流状态。接受类别为待办事项、待办事项、活动、已完成或已取消；taskType可以是ID或显示名称，省略会将状态应用于项目类型中的每个任务类型。

测试管理

工具	说明
`list_test_projects`	列出测试管理项目。返回按名称排序的测试项目。这些与跟踪器项目是分开的。
`list_test_suites`	列出测试项目中的测试套件。接受项目ID或名称。嵌套套件的可选父过滤器。
`get_test_suite`	在测试项目中按ID或名称获取单个测试套件。返回套件详细信息和测试用例计数。
`create_test_suite`	在测试项目中创建测试套件。Idempotent：如果存在同名套件（created=false），则返回现有套件。嵌套的可选父对象。
`update_test_suite`	更新测试套件。接受套房ID或名称。仅修改提供的字段。
`delete_test_suite`	永久删除测试套件。接受套房ID或名称。此操作无法撤消。
`list_test_cases`	列出测试项目中的测试用例。可选过滤器：套件（ID或姓名）、受让人（姓名或电子邮件）。
`get_test_case`	在测试项目中按ID或名称获取单个测试用例。
`create_test_case`	创建附加到套件的测试用例。需要项目和套件。默认值：类型=功能，优先级=中等，状态=草稿。
`update_test_case`	更新测试用例。接受测试用例ID或名称。仅修改提供的字段。将受让人设置为null以取消分配。
`delete_test_case`	永久删除测试用例。接受测试用例ID或名称。此操作无法撤消。
`list_test_plans`	列出测试管理项目中的测试计划。返回计划名称和ID。需要项目ID或名称。
`get_test_plan`	获取测试计划的详细信息，包括其项目（测试用例）。接受项目中的计划ID或名称。
`create_test_plan`	在项目中创建测试计划。Idempotent：如果存在同名计划（created=false），则返回现有计划。
`update_test_plan`	更新测试计划的名称或描述。仅修改提供的字段。传递描述=空以清除。
`delete_test_plan`	永久删除测试计划。这不会删除关联的测试运行。无法撤消。
`add_test_plan_item`	将测试用例添加到测试计划中。按ID或名称解析测试用例。可选择通过电子邮件或姓名指定人员。
`remove_test_plan_item`	按项目ID从测试计划中删除测试用例。从Get_test_plan获取项目ID。
`list_test_runs`	列出测试管理项目中的测试运行。返回跑步名称、ID和截止日期。
`get_test_run`	获取包括所有结果在内的测试运行详细信息。接受项目中的运行ID或名称。
`create_test_run`	在项目中创建测试运行。对于从计划批量创建，请使用run_test_plan。
`update_test_run`	更新测试运行的名称、描述或截止日期。仅修改提供的字段。传递null以清除可选字段。
`delete_test_run`	永久删除测试运行。这不会删除关联的测试结果。无法撤消。
`list_test_results`	列出测试运行中的测试结果。返回结果名称、状态和受让人。
`get_test_result`	获取测试结果详细信息。接受结果ID或名称。
`create_test_result`	在运行中创建测试结果。按ID或名称解析测试用例。状态默认为“未测试”。
`update_test_result`	更新测试结果的状态、受让人或描述。状态值：未测试、已阻止、已通过、失败。
`delete_test_result`	永久删除测试结果。无法撤消。
`run_test_plan`	执行测试计划：为每个计划项创建一个测试运行和一个测试结果。返回运行ID和创建的结果计数。（可选）命名跑步并设置截止日期。

故障排除

带有特殊字符的密码

如果您的Huly密码包含以下字符 *, %, !，或 #，通过CLI传递它 -e 标志可能会失败，因为shell会在这些字符到达进程之前对其进行解释。

解决方案：直接编辑MCP配置文件，而不是使用 claude mcp add -e.In ~/.claude.json （用户范围）或 .mcp.json （项目范围），JSON本机处理所有特殊字符：

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "node",
      "args": ["path/to/dist/index.cjs"],
      "env": {
        "HULY_URL": "https://your-huly-instance.com",
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "p@ss*w0rd!#%",
        "HULY_WORKSPACE": "your-workspace"
      }
    }
  }
}

或者，使用 HULY_TOKEN 代替电子邮件/密码完全绕过密码身份验证（请参阅环境变量).

MCP客户端显示“重新连接失败”

更改MCP配置后，一些客户端（包括Claude Code）需要完全重新启动，而不仅仅是重新连接。完全退出应用程序并重新打开。

您可以通过以下方式验证连接是否独立工作：

claude mcp list  # Should show "Connected"

自托管Huly：登录尝试失败后帐户被锁定

Huly在5次API身份验证尝试失败后锁定密码登录。这通常发生在密码配置错误的初始设置过程中。在服务重新启动时，锁会一直存在于数据库中。

症状: PasswordLoginLocked MCP服务器出错，Huly web UI显示“由于尝试失败次数过多，密码登录已锁定。请使用OTP登录方法解锁您的帐户。”（如果不配置SMTP，OTP将无法工作。）

修复 --重置CockroachDB中的锁计数器：

# Find your account UUID and check lock status
docker exec -e PGPASSWORD=  \
  cockroach sql --host=localhost --user= --database=defaultdb --insecure \
  -e "SELECT uuid, failed_login_attempts FROM global_account.account;"

# Reset the counter
docker exec -e PGPASSWORD=  \
  cockroach sql --host=localhost --user= --database=defaultdb --insecure \
  -e "UPDATE global_account.account SET failed_login_attempts = 0 WHERE uuid = '';"

CockroachDB凭据可以在您的Huly中找到 compose.yml 或通过 docker exec env | grep COCKROACH.

Windows特定注意事项

Bash包装脚本 （采购 .env 文件）在Windows上由MCP客户端启动时可能无法可靠工作。最好直接在MCP配置JSON中设置env变量。
Docker接管SSH 由于凭据管理器问题，在Windows上可能会失败。如果需要，从服务器桌面提取图像。

Huly MCP

快速接入

详细介绍