mcpField
H
Huly Mcp

Huly Mcp

本地服务
github.com/dugynoo生产力04 天前更新
代码仓库

关于 Huly Mcp

Huly Mcp 将 Huly 项目管理功能开放给 MCP 客户端，覆盖项目、问题、文档、日历和工时等领域。它支持自定义任务类型、项目状态工作流，并提供 Process 插件的只读工具。

主要功能

  1. 01覆盖 23 类管理功能
  2. 02支持问题与项目管理
  3. 03支持自定义任务类型和状态
  4. 04提供 Process 插件只读工具
  5. 05可按类别筛选工具集

适用场景

  1. 01通过 MCP 管理 Huly 项目和问题
  2. 02维护评论、文档及附件
  3. 03查看流程与执行记录
  4. 04按需限制可用工具类别

MCP 相关

这是供 MCP 客户端连接的 Huly MCP 服务，支持 stdio 和 Streamable HTTP 传输。可通过 `TOOLSETS` 选择对客户端开放的工具类别。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": [
        "-y",
        "@dugynoo/huly-mcp"
      ],
      "env": {
        "HULY_URL": "<HULY_URL>",
        "HULY_EMAIL": "<HULY_EMAIL>",
        "HULY_PASSWORD": "<HULY_PASSWORD>",
        "HULY_WORKSPACE": "<HULY_WORKSPACE>"
      }
    }
  }
}
启动命令npx -y @dugynoo/huly-mcp
需要配置的环境变量
HULY_URL
HULY_EMAIL
HULY_PASSWORD密钥
HULY_WORKSPACE

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@dugynoo/huly-mcp

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

@dugynoo/huly-mcp

npm npm downloads License: MIT MCP TypeScript MCP Server

用于集成 Huly 的 MCP 服务——包含 23 个类别的 209 个工具（问题、项目、任务、评论、文档、卡片、频道、日历、时间跟踪、测试管理、流程、自定义字段、附件、潜在客户等）。支持自定义任务类型、项目范围内的状态工作流，以及 Process 插件的读取工具。

安装

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

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@dugynoo/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "[email protected]",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}
Claude Code 
claude mcp add huly \
  -e HULY_URL=https://huly.app \
  -e [email protected] \
  -e HULY_PASSWORD=yourpassword \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @dugynoo/huly-mcp@latest

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

Claude Desktop

将标准配置添加到 claude_desktop_config.json：

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

添加到用户设置（.vscode/mcp.json），或使用命令面板 → “MCP: Add Server”：

{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@dugynoo/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "[email protected]",
        "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", "@dugynoo/huly-mcp@latest"],
      "environment": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "[email protected]",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }

更新

安装命令中的 @latest 标签始终会获取最新版本。大多数 MCP 客户端会缓存已安装的软件包，因此需要强制重新获取：

客户端更新方法
Claude Code执行 claude mcp remove huly，然后使用上方的安装命令重新添加
Claude Desktop重启应用（启动时会运行 npx）
VS Code / Cursor从命令面板重启 MCP 服务，或重新加载窗口
npx (manual)npx -y @dugynoo/huly-mcp@latest — 当 @latest 指向新版本时，-y 标志会跳过缓存

HTTP 传输

默认情况下，服务使用 stdio 传输。要使用 HTTP 传输（Streamable HTTP）：

HULY_URL=https://huly.app \
[email protected] \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @dugynoo/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 @dugynoo/huly-mcp@latest

环境变量

变量必填描述
HULY_URL是Huly 实例 URL
HULY_EMAIL身份验证*账户邮箱
HULY_PASSWORD身份验证*账户密码
HULY_TOKEN身份验证*API 令牌（可替代邮箱/密码）
HULY_WORKSPACE是工作区标识符
HULY_CONNECTION_TIMEOUT否连接超时时间，单位为 ms（默认值：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。

与 @firfi/huly-mcp 的差异

此软件包是 @firfi/huly-mcp 的下游版本，并新增了两项功能：

  • 在 create_issue 和 update_issue 上添加 taskType 参数，以便使用自定义任务类型（例如 Ticket、Bug、Feature）以及项目范围内的状态工作流（Created、Awaiting approval 等）创建问题。没有此参数时，即使项目定义了自己的任务类型，通过 MCP 创建的问题仍会回退到默认任务类型。
  • 只读 Process 插件工具：list_processes、get_process、list_executions。需要启用了 Process 插件的 Huly 服务（v0.7.382+）。

原上游版权信息保留在 LICENSE 中。

可用工具

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

项目
工具描述
list_projects列出所有 Huly 项目。按名称排序返回项目。支持按归档状态筛选。
get_project获取 Huly 项目的完整详情，包括其状态。返回项目名称、描述、归档标记、默认状态和所有可用状态。
list_statuses列出 Huly 项目的所有问题状态及其类别信息。返回状态名称、isDone、isCanceled 和 isDefault 标记。创建或更新问题前，可用此工具查找有效状态。
create_project创建新的 Huly tracker 项目。具有幂等性：如果已存在具有相同标识符的项目，则返回该项目（created=false）。标识符必须为 1 到 5 个大写字母数字字符，且以字母开头。
update_project更新 Huly 项目。仅修改已提供的字段。将描述设为 null 可清除描述。
delete_project永久删除 Huly 项目。此项目中的所有问题、里程碑和组件都将成为孤立项。此操作无法撤销。
问题
工具描述
preview_deletion在实际删除 Huly 实体之前，预览删除的影响。显示受影响的子实体、关系和警告。支持问题、项目、组件和里程碑。调用删除操作前，使用此工具了解级联影响。
list_issues查询 Huly 问题，可选使用筛选条件。返回按修改日期排序的问题（最新的排在前面）。支持按项目、状态、受派人、组件和 parentIssue 筛选（以列出特定问题的子问题）。支持按标题子字符串（titleSearch）和描述内容（descriptionSearch）搜索。
get_issue获取 Huly 问题的完整详情，包括 Markdown 描述。使用此工具查看问题内容、评论或完整元数据。
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在两个问题之间添加关系。关系类型：'blocks'（源问题阻止目标问题——添加到目标问题的 blockedBy 中）、'is-blocked-by'（源问题被目标问题阻止——添加到源问题的 blockedBy 中）、'relates-to'（双向链接——更新两侧）。targetIssue 接受跨项目标识符，例如 'OTHER-42'。如果关系已存在，则不执行任何操作。
remove_issue_relation移除两个问题之间的关系。与 add_issue_relation 相对应：'blocks' 从目标问题的 blockedBy 中移除，'is-blocked-by' 从源问题的 blockedBy 中移除，'relates-to' 从两侧移除。如果关系不存在，则不执行任何操作。
list_issue_relations列出某个问题的所有关系。返回 blockedBy（阻止此问题的问题）、relations（双向问题链接）和 documents（含标题／团队空间信息的已链接文档）。不会返回此问题所阻止的问题——请在目标问题上使用 list_issue_relations 查看。
link_document_to_issue将 Huly 文档链接到问题。此链接会显示在界面中问题的“关系”面板里。幂等：如果文档已链接，则不执行任何操作。使用 list_issue_relations 查看已链接的文档。
unlink_document_from_issue从问题中移除文档链接。幂等：如果文档未链接，则不执行任何操作。
评论
工具说明
list_comments列出 Huly 问题中的评论。按创建日期排序（从早到晚）。包含线程回复的评论会将回复放在 replies 数组中（从早到晚）。
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 文档团队空间。幂等：如果存在同名团队空间，则返回现有团队空间。
update_teamspace更新现有 Huly 文档团队空间的字段。仅修改已提供的字段。将 description 设为 null 可清除描述。
delete_teamspace永久删除 Huly 文档团队空间。此操作无法撤销。
list_documents列出 Huly 团队空间中的文档。按修改日期排序（从新到旧）。每个结果都包含指向 Huly Web 应用中该文档的 'url' 字段。支持按标题子串 (titleSearch) 和内容 (contentSearch) 搜索。
get_document获取 Huly 文档的完整详情，包括 Markdown 内容以及指向 Huly Web 应用中该文档的 'url' 字段。用于查看文档内容和元数据。
create_document在 Huly 团队空间中创建新文档。内容支持完整 Markdown，包括原生 Mermaid 图表（```mermaid 代码块会在 Huly UI 中交互式呈现）。可选地传入父文档的标题或 ID 作为 parent，以创建嵌套子文档；父文档无效时会报错，而不会静默创建顶层文档。返回已创建文档的 id，以及指向 Huly Web 应用中该文档的 'url' 字段。使用 link_document_to_issue 将文档关联到跟踪器问题。
edit_document编辑现有 Huly 文档。支持两种互斥的内容模式：(1) 使用 'content' 完整替换；(2) 使用 'old_text' + 'new_text' 定向搜索并替换。除非 replace_all 为 true，否则匹配多处时会报错。将 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 或 data。
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 视图中。此操作幂等，可安全用于已是客户的组织。接受组织 ID 或唯一的精确名称。
add_organization_channel为按 ID 或唯一的精确名称标识的组织添加联系渠道（电话、电子邮件、网站/主页、LinkedIn、Twitter、GitHub、Facebook、Telegram）。提供方名称：email、phone、linkedin、twitter、github、facebook、telegram、homepage。
add_organization_member将人员关联为组织成员。该人员会显示在 Huly 组织的 Members 选项卡下。使用人员 ID 或电子邮件地址来识别人员。此操作幂等：如果该人员已经是成员，则返回 added=false。
list_organization_members列出组织的所有成员。返回每位成员的人员 ID、姓名和主要电子邮件地址（如果有）。使用名称而非 ID 时，该名称必须唯一对应一个组织。
list_person_organizations列出人员所属的所有组织。提供 personId 或电子邮件地址。返回每个组织的 ID 和名称。
remove_organization_member将人员从组织成员中移除。与 add_organization_member 的操作相反。如果该人员不是成员，则返回 removed: 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）。此操作具有幂等性：如果与该参与者的私信已存在，则返回该私信（created: false）；否则创建新的私信（created: true）。返回的 id 可作为 dm 参数传给 send_dm_message、list_dm_messages 等工具。
list_dm_messages列出私信对话中的消息，按最新优先排序。dm 参数接受私信 _id 或参与者的显示名称（例如 Kerr,Shannon）；名称仅会解析为与已验证账户的一对一私信。
send_dm_message向私信对话发送消息。dm 参数接受私信 _id 或参与者的显示名称；名称仅会解析为与已验证账户的一对一私信。消息正文支持 Markdown 格式。
update_dm_message更新私信消息。dm 参数接受私信 _id 或参与者的显示名称；名称仅会解析为与已验证账户的一对一私信。只能修改正文。
delete_dm_message永久删除私信消息。dm 参数接受私信 _id 或参与者的显示名称；名称仅会解析为与已验证账户的一对一私信。此操作无法撤销。
list_thread_replies列出消息线程中的回复。返回按日期排序的回复（最早的在前）。
add_thread_reply在消息线程中添加回复。回复正文支持 Markdown 格式。
update_thread_reply更新线程回复。只能修改正文。
delete_thread_reply永久删除线程回复。此操作无法撤销。
日历
工具描述
list_events列出日历活动。返回按日期排序的活动。支持按日期范围筛选。
list_calendars列出可写入且未隐藏的日历，这些日历可用作 create_event 或 create_recurring_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列出重复活动的实例。返回按日期排序的实例。支持按日期范围筛选。使用 includeParticipants=true 可获取完整参与者信息（需要额外查询）。
时间跟踪
工具描述
log_time记录在 Huly 问题上花费的时间。记录一条可选带描述的时间条目。时间值以分钟为单位。
get_time_report获取特定 Huly 问题的时间跟踪报告。显示总时间、预估时间、剩余时间以及所有时间条目。
list_time_spend_reports列出所有问题的时间条目。支持按项目和日期范围筛选。返回按日期排序的条目（最新的在前）。
get_detailed_time_report获取项目的详细时间明细。显示按问题和员工分组的总时间。支持按日期范围筛选。
list_work_slots列出已安排的工作时段。显示关联到待办事项的计划时间块。支持按员工和日期范围筛选。
create_work_slot创建已安排的工作时段。将时间块关联到待办事项，用于规划。
start_timer在 Huly 问题上启动客户端计时器。验证问题是否存在，并返回开始时间戳。完成后使用 log_time 记录经过的时间。
stop_timer停止 Huly 问题上的客户端计时器。返回停止时间戳。根据开始和停止时间戳计算经过的时间，并使用 log_time 记录。
dedup_planner_todos移除重复的 Planner 待办事项；Huly 服务有时会为同一个问题创建多个副本
搜索
工具描述
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更新工作区成员的角色。需要相应权限。有效角色：READONLYGUEST、DocGuest、GUEST、USER、MAINTAINER、OWNER、ADMIN。
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。设置 personalized=false，并提供 notBefore 和过期时间，即可创建可重复使用的匿名访客链接；还可通过 spaces 将访问限制为特定的 Huly 空间 ID。
get_regions获取创建工作区时可用的区域。返回区域代码和显示名称。
关联
工具描述
list_associations列出工作区中的 Huly 关联定义。每个关联都是两个文档类之间的类型化链接（例如，Person ↔ Organization，基数为 1:1 / 1:N / N:N）。可按 classA 或 classB 筛选。
create_association在两个文档类之间创建新的 Huly 关联。幂等：如果具有相同 (classA, classB, nameA, nameB) 元组的关联已存在，则返回该关联。
list_relations列出 Huly 关系，即文档之间的具体链接。可按 association（ID）、docA（源文档 ID）或 docB（目标文档 ID）筛选。
create_relation通过现有的关联链接两个文档。幂等：如果相同的关联已连接 (docA, docB)，则返回现有关系。
delete_relation移除两个文档之间的关系。幂等：如果该关系已不存在，则返回 deleted=false。
卡片
工具描述
list_card_spaces列出所有 Huly 卡片空间。返回按名称排序的卡片空间。卡片空间是卡片的容器。
list_master_tags列出 Huly 卡片空间中可用的主标签（卡片类型）。主标签定义了可在空间中创建的卡片类型/架构。
list_cards列出 Huly 卡片空间中的卡片。返回按修改日期排序的卡片（最新的排在前面）。支持按类型（主标签）、标题子串和内容搜索筛选。
get_card获取 Huly 卡片的完整详情，包括 Markdown 内容。可用此工具查看卡片内容和元数据。
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查询漏斗中的 Huly 潜在客户，并可选应用筛选条件。传入 list_funnels 返回的漏斗 ID，或传入漏斗名称以便查找。返回的潜在客户按修改日期排序（最新的在前）。支持按状态、受派人和标题搜索筛选。
get_lead获取 Huly 潜在客户的完整详情，包括 Markdown 描述、客户名称、漏斗 ID 和漏斗名称，以及状态。潜在客户标识符采用上游 Huly 格式，例如 'LEAD-1'。
create_lead在 Huly 漏斗中创建潜在客户。customer 是组织名称：如果存在名称匹配的组织，则重复使用；否则会创建一个带有 Customer mixin 的新组织。可选填写 Markdown 描述、初始状态名称和受派人。返回 LEAD-N 标识符、潜在客户 ID 和漏斗 ID。要附加文件，请使用 add_attachment，并将 objectClass 设为 'lead:class:Lead'、objectId 设为返回的 ID，space 设为返回的 funnelId。
update_lead更新由 LEAD-N 标识的 Huly 潜在客户。仅更新提供的字段：状态（按名称）、标题、Markdown 描述、受派人（电子邮件或姓名；设为 null 可取消指派）。
流程
工具描述
list_processes列出工作区中的 Huly 流程定义。每个流程都是附加到卡片类（master tag）的工作流。可选按 masterTag 筛选，以查找特定卡片类型的流程。只读。
get_process按 ID 或显示名称获取单个 Huly 流程定义。返回名称、描述、主标签以及启动/自动化标志。只读。
list_executions列出流程执行——针对特定卡片运行的进行中或已完成的工作流。可按 process（ID 或名称）、card（卡片 ID）或 status（active/done/cancelled）筛选。每条执行记录都包含当前工作流状态和错误标志。只读。
start_process针对卡片启动新的流程执行。按 ID 或显示名称解析流程，并在第一个工作流状态（最低排名）创建一个活跃的执行。随后，Huly 服务的流程引擎会自动触发 OnExecutionStart 触发器，以推进该执行。
cancel_execution将进行中的流程执行状态设为 'cancelled'，以取消该执行。幂等——已取消的执行会返回 cancelled=false。
标签类别
工具描述
list_tag_categories列出工作区中的标签/标记类别。类别用于归组标签（例如，'Priority Labels'、'Type Labels'）。可选使用 targetClass 筛选（默认为全部）。
create_tag_category创建新的标签/标记类别。此操作是幂等的：如果已存在 label 和 targetClass 相同的类别，则返回该类别（created=false）。targetClass 默认为 tracker 问题。
update_tag_category更新标签/标记类别。接受类别 ID 或标签名称。仅修改提供的字段。
delete_tag_category永久删除标签/标记类别。接受类别 ID 或标签名称。此类别中的标签将成为孤立项（不会被删除）。此操作无法撤销。
任务管理
工具描述
list_project_types列出 Huly 跟踪器项目类型／工作流模板。返回 ID、显示名称、描述符、任务类型数量、状态数量，以及该类型是否看起来是默认的 Classic 跟踪器类型。
get_project_type一次调用即可检查一个 Huly 跟踪器项目类型。接受 projectType 的 ID 或显示名称；省略时使用明确无歧义的 Classic 跟踪器类型。返回任务类型、状态、类别以及任务类型到状态的映射。
list_task_types列出 Huly 问题／任务类型。可选择按项目类型 ID 或显示名称筛选。返回任务类型标识、父项目类型、种类、问题类别以及可用状态数量。
create_task_type在项目类型中按规范化名称幂等地添加 Huly 问题／任务类型。除非指定 templateTaskType，否则会从现有模板任务类型复制必需的工作流配置。返回 created、ID、受影响的任务类型 ID，以及工作区级工作流警告。
create_issue_status在项目类型和任务类型范围内，按规范化名称幂等地添加 Huly 问题工作流状态。category 接受 backlog、todo、active、done 或 canceled；taskType 可以是 ID 或显示名称，省略时会将该状态应用于项目类型中的所有任务类型。
测试管理
工具描述
list_test_projects列出测试管理项目。按名称排序返回测试项目。这些项目与跟踪器项目相互独立。
list_test_suites列出测试项目中的测试套件。接受项目 ID 或名称。可选按父级筛选嵌套套件。
get_test_suite在测试项目中按 ID 或名称获取单个测试套件。返回套件详情和测试用例数量。
create_test_suite在测试项目中创建测试套件。幂等：如果存在同名套件，则返回现有套件（created=false）。可选指定父级以进行嵌套。
update_test_suite更新测试套件。接受套件 ID 或名称。仅修改提供的字段。
delete_test_suite永久删除测试套件。接受套件 ID 或名称。此操作无法撤销。
list_test_cases列出测试项目中的测试用例。可选筛选条件：套件（ID 或名称）、受派人（姓名或电子邮件）。
get_test_case在测试项目中按 ID 或名称获取单个测试用例。
create_test_case创建并关联到套件的测试用例。需要项目和套件。默认值：type=functional、priority=medium、status=draft。
update_test_case更新测试用例。接受测试用例 ID 或名称。仅修改提供的字段。将 assignee 设为 null 可取消分配。
delete_test_case永久删除测试用例。接受测试用例 ID 或名称。此操作无法撤销。
list_test_plans列出测试管理项目中的测试计划。返回计划名称和 ID。需要项目 ID 或名称。
get_test_plan获取测试计划详情，包括其条目（测试用例）。接受项目中的计划 ID 或名称。
create_test_plan在项目中创建测试计划。幂等：如果存在同名计划，则返回现有计划（created=false）。
update_test_plan更新测试计划的名称或描述。仅修改提供的字段。传入 description=null 可清除描述。
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 或名称查找测试用例。状态默认为 'untested'。
update_test_result更新测试结果的状态、受派人或描述。状态值：untested、blocked、passed、failed。
delete_test_result永久删除测试结果。此操作无法撤销。
run_test_plan执行测试计划：创建一个测试运行，并为每个计划条目创建一个测试结果。返回运行 ID 和创建的结果数量。可选为运行命名并设置截止日期。
用户状态
工具描述
list_user_statuses列出 Huly 用户在线状态记录：当前在线的用户、其账户 UUID 以及最后一次状态变更的时间戳。可按 online（true/false）或 user（账户 UUID）筛选。此工具为只读；在线状态由服务器根据 websocket 连接状态维护。

故障排除

包含特殊字符的密码

如果你的 Huly 密码包含 *、%、! 或 # 等字符，通过 CLI -e 标志传递密码可能会失败，因为 shell 会在这些字符传递给进程之前对其进行解析。

解决方案：直接编辑 MCP 配置文件，而不是使用 claude mcp add -e。在 ~/.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": "[email protected]",
        "HULY_PASSWORD": "p@ss*w0rd!#%",
        "HULY_WORKSPACE": "your-workspace"
      }
    }
  }
}

或者，使用 HULY_TOKEN 代替邮箱/密码，以完全绕过密码验证（参见环境变量）。

MCP 客户端显示“Failed to reconnect”

更改 MCP 配置后，部分客户端（包括 Claude Code）需要完全重启，而不只是重新连接。请完全退出应用并重新打开。

你可以通过以下方式独立验证连接是否正常：

claude mcp list  # Should show "Connected"
自托管 Huly：多次登录失败后账户被锁定

Huly 在 5 次 API 身份验证失败后会锁定密码登录。初始设置时密码配置错误，常会导致此问题。服务重启后，数据库中的锁定状态仍会保留。

症状：MCP 服务返回 PasswordLoginLocked 错误，且 Huly 网页界面显示“由于登录尝试次数过多，密码登录已锁定。请使用 OTP 登录方式解锁账户。”（未配置 SMTP 时，OTP 无法使用。）

修复方法 — 在 CockroachDB 中重置锁定计数器：

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

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

CockroachDB 凭据可在 Huly 的 compose.yml 中找到，也可以通过 docker exec <cockroach_container> env | grep COCKROACH 获取。

Windows 特定说明
  • Bash 包装脚本（加载 .env 文件）由 Windows 上的 MCP 客户端启动时可能无法可靠运行。建议直接在 MCP 配置 JSON 中设置环境变量。
  • 由于凭据管理器问题，通过 SSH 拉取 Docker 镜像在 Windows 上可能会失败。如有需要，请从服务器桌面拉取镜像。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。