huly-mcp-sdk

最完整的 MCP 服务器，适用于 Huly —— 开源项目管理平台。

将 Claude Desktop（以及任何兼容 MCP 的客户端）直接连接到你的 Huly 工作区。通过自然语言管理项目、问题、里程碑、组件、文档、标签等。

工具（共 36 个）

Related MCP server: Huly MCP Server

要求

• Node.js >= 20

• 一个 Huly 账户 — huly.app（云版）或自托管

快速开始

npx huly-mcp-sdk setup

这会运行交互式设置向导 — 向你的邮箱发送一次性验证码（也适用于 Google/GitHub SSO 账户），并自动写入你的 .env 文件。

你的工作区 slug 是 Huly URL 中域名之后的部分：huly.app/myteam → slug 为 myteam。

兼容的客户端

同一个 MCP 服务器适用于所有主流 AI 编码工具。选择你的客户端。

认证说明： 下面的所有配置示例都使用 HULY_TOKEN。如果遇到令牌过期问题，请改用邮箱 + 密码 — 只需将 env 块替换为：

"HULY_EMAIL": "your@email.com",
"HULY_PASSWORD": "yourpassword",
"HULY_WORKSPACE": "your-workspace-slug"

有关这两种方式的详细信息，请参阅手动认证。

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

保存后重启 Claude Desktop。

Claude Code (CLI)

claude mcp add huly -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk

或者仅将其限定到单个项目：

claude mcp add huly --scope project -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk

验证是否已连接：claude mcp list

Cursor

创建或编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

重启 Cursor。工具会出现在 MCP 下的 Agent 面板中。

Windsurf (Codeium)

创建或编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

重启 Windsurf。MCP 工具可供 Cascade AI 面板使用。

VS Code — Cline 扩展

1. 安装 Cline 扩展

2. 打开 Cline 设置 → MCP Servers → Edit MCP Settings

3. 添加：

{
  "huly": {
    "command": "npx",
    "args": ["huly-mcp-sdk"],
    "env": {
      "HULY_TOKEN": "your-token",
      "HULY_WORKSPACE": "your-workspace-slug"
    }
  }
}

VS Code — Continue 扩展

1. 安装 Continue 扩展

2. 编辑 ~/.continue/config.json，并将其添加到 mcpServers 数组中：

{
  "mcpServers": [
    {
      "name": "huly",
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  ]
}

Zed

编辑 ~/.config/zed/settings.json，并添加一个 context_servers 条目：

{
  "context_servers": {
    "huly": {
      "command": {
        "path": "npx",
        "args": ["huly-mcp-sdk"],
        "env": {
          "HULY_TOKEN": "your-token",
          "HULY_WORKSPACE": "your-workspace-slug"
        }
      }
    }
  }
}

OpenAI Codex CLI

编辑 ~/.codex/config.json，并添加到 mcpServers：

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

任何其他兼容 MCP 的客户端

该服务器使用标准的 stdio 传输。如果你的工具支持 MCP，配置模式始终相同：

• command: npx

• args: ["huly-mcp-sdk"]

• env: HULY_TOKEN + HULY_WORKSPACE

有关确切的配置文件位置，请查阅你的工具的 MCP 文档。

替代方案（避免 npx 冷启动）： 克隆并构建一次，然后直接指向编译后的二进制文件：

git clone https://github.com/varaprasadreddy9676/huly-mcp.git
cd huly-mcp && npm install && npm run build

在上面的任何配置中，将 "command": "npx", "args": ["huly-mcp-sdk"] 替换为 "command": "node", "args": ["/absolute/path/to/huly-mcp/dist/index.js"]。

示例提示

项目与问题：

• "创建一个名为 'Mobile App' 的新项目，标识符为 MOBILE"

• "列出 PROJ 项目中所有进行中的问题"

• "在 PROJ 中创建一个高优先级问题，标题为 '修复登录超时'"

• "将 PROJ-42 的状态更新为 Done，将其分配给 Sarah，并移动到 Auth 组件"

• "搜索与身份验证相关的问题"

• "在 PROJ-15 上添加评论，说明修复已部署"

• "列出 PROJ-42 上的所有评论以查看讨论"

里程碑与组件：

• "在 PROJ 中创建里程碑 'v2.0 Launch'，目标日期为 2026-06-01"

• "列出 PROJ 项目的里程碑"

• "在 PROJ 中创建名为 'Auth' 的组件"

• "列出 PROJ 中的所有组件"

标签与关系：

• "将标签 'bug' 添加到 PROJ-42"

• "创建一个名为 'backend' 的标签，颜色为 #3b82f6"

• "将 PROJ-55 标记为被 PROJ-12 阻塞"

• "将 PROJ-42 设置为 PROJ-5 的子任务"

时间跟踪：

• "在 PROJ-42 上记录 2.5 小时，用于数据库重构"

文档：

• "列出 Engineering 团队空间中的所有文档"

• "在 Engineering 团队空间中创建名为 'API Design' 的文档"

• "使用以下 Markdown 更新 API Design 文档：..."

• "向 EP1 文档添加 Mermaid 架构图"

• "将文档 abc123 链接到问题 PROJ-42"

• "删除 PROJ-15 上的第二条评论"

文档内容

读取：get_document

get_document 始终返回完整的元数据（标题、团队空间、评论、快照）。要同时获取并显示文本内容，请设置可选的 HULY_FRONT_URL 环境变量：

"env": {
  "HULY_TOKEN": "...",
  "HULY_WORKSPACE": "myteam",
  "HULY_FRONT_URL": "https://front.huly.app"
}

对于自托管的 Huly，请将 HULY_FRONT_URL 设置为你的前端服务 URL（例如 http://localhost:8083）。

写入：update_document

update_document 接受一个 documentId 和一个 markdown 字符串，并直接将丰富的结构化内容写入文档 — 无需手动编辑。

支持的 Markdown：

示例：

update_document({
  documentId: "abc123",
  markdown: `# Service Flow\n\n` +
    `## Architecture\n\n` +
    "```mermaid\n" +
    "flowchart TD\n" +
    "  A([User]) --> B[Browse Catalogue]\n" +
    "  B --> C[Pay via Razorpay]\n" +
    "  C --> D[Order Confirmed]\n" +
    "```\n\n" +
    "## Business Rules\n\n" +
    "- Payment required before confirmation\n" +
    "- All orders synced to HIS\n"
})

Mermaid 代码块会在 Huly 的文档编辑器中渲染为实时交互式图表 — 而不是代码块。

批量 CSV 导入

从 CSV 文件一次导入多个问题 — 适用于从其他工具迁移：

node scripts/import-csv.js tasks.csv PROJ

CSV 格式：

title,priority,status,dueDate
Fix login bug,High,In Progress,2025-04-01
Add dark mode,Medium,,
Improve performance,Urgent,,2025-05-01

必填列：title。可选：priority（Urgent/High/Medium/Low）、status（必须与项目中的状态名称匹配）、dueDate（YYYY-MM-DD）。

手动认证

在项目根目录创建 .env 文件（或通过客户端配置中的 env 传递）：

选项 A — 邮箱 + 密码（推荐）：

如果你的 Huly 账户设置了密码，则可以使用此方式（个人资料 → 安全 → 更改密码）。

HULY_EMAIL=your@email.com
HULY_PASSWORD=yourpassword
HULY_WORKSPACE=your-workspace-slug

选项 B — 令牌：

HULY_WORKSPACE=your-workspace-slug
HULY_TOKEN=your-token-here

要获取令牌：访问 huly.app → 打开浏览器 DevTools → Application → Local Storage → https://huly.app → 复制 token 值。

令牌会在一段时间后过期。如果遇到认证错误，请切换到邮箱 + 密码认证，或从 DevTools 刷新令牌。

自托管 Huly：

HULY_ACCOUNTS_URL=https://your-huly-instance.com/account
HULY_FRONT_URL=https://your-huly-instance.com

架构

• 单一长连接 WebSocket 连接 — 通过 @hcengineering/server-client 在每个进程中连接一次，而不是每次工具调用都连接（模型加载需要 1–3 秒，因此这可以保持工具快速响应）

• 延迟初始化 — 在首次工具调用时连接，以便认证错误在 Claude 中清晰显示

• 双重认证 — OTP 令牌（适用于 Google/GitHub SSO）或邮箱 + 密码

• Stdio 传输 — 标准 MCP 传输，兼容 Claude Desktop 和任何 MCP 客户端

更新日志

v0.5.6 — delete_document

• 新增：delete_document — 按 ID 永久删除文档

v0.5.5 — create_teamspace

• 新增：create_teamspace — 创建新的文档团队空间（用于按项目或团队组织文档的顶级文件夹）

v0.5.2 — delete_comment + link_document

• 新增：delete_comment — 按 ID 从问题中删除特定评论；list_comments 现在会在输出中包含评论 ID

• 新增：link_document — 将 Huly 文档链接到问题；该文档会显示在问题的 Relations 面板中

v0.5.0 — 文档写入 + 错误修复

• 新增：update_document — 以编程方式将 Markdown 写入任意 Huly 文档；\``mermaid` 代码块使用 Huly 的原生节点类型，并渲染为交互式图表

• 修复：IssueStatus 查询 — 状态在 Huly 中全局存储（core:space:Model），而非按项目存储；移除了导致 create_issue、update_issue 和 list_issues 出现 "未找到状态" 错误的错误空间过滤器

• 修复：create_project — 设置 members: [currentUser]，使新建项目立即可在 Huly UI 中显示

v0.4.0

• log_time、list_comments、update_issue 支持组件/里程碑分配

v0.3.1

• get_document、create_document

v0.3.0

• create_project、create_milestone、问题支持指派对象

链接

• npm：https://www.npmjs.com/package/huly-mcp-sdk

• GitHub：https://github.com/varaprasadreddy9676/huly-mcp

• MCP Registry：https://registry.modelcontextprotocol.io（搜索 "huly-mcp"）

许可证

Eclipse Public License 2.0