Hatchet MCP

hatchet-mcp

一个 MCP 服务，可让 AI Agent 观察和操作 Hatchet 工作流，包括状态、运行、日志、工作节点和指标，以及触发 / 取消 / 重放。

原因： Hatchet 有出色的 API，但没有 MCP。这个服务对其进行封装，让 Agent（Claude Code / Desktop 等）能够查看和操作工作流状态。

安装

将以下内容添加到 Claude Code / Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "hatchet": {
      "command": "npx",
      "args": ["-y", "hatchet-mcp"],
      "env": { "HATCHET_CLIENT_TOKEN": "<your-hatchet-api-token>" }
    }
  }
}

从 Hatchet 控制面板 → API tokens 获取令牌。该令牌是一个编码了服务 URL 和租户信息的 JWT，因此它是唯一必需的设置项。

配置

变量	必需	描述
HATCHET_CLIENT_TOKEN	是	Hatchet API 令牌（JWT）。其中编码了服务 URL 和租户信息，因此通常只需此项。
HATCHET_API_BASE	否	覆盖 API 基础 URL。可自托管的用户可以将其指向任意 Hatchet 实例。
HATCHET_TENANT_ID	否	覆盖从令牌中解码出的租户 ID。

要自托管？将 HATCHET_API_BASE 设置为你自己的 Hatchet 实例，即可在任何地方使用。

工具

可观测性（只读）

工具	描述
whoami	显示解析后的 Hatchet 租户和服务 URL，并确认令牌有效。
list_workflows	列出该租户的工作流定义。
list_runs	列出工作流运行（可选回溯时间窗口和筛选条件）。
get_run	获取某次工作流运行的完整详情——状态、任务和错误。
get_run_logs	根据任务的外部 ID 获取日志行。
list_workers	列出工作节点及其状态。
get_queue_metrics	获取该租户的任务 / 队列指标（队列运行状况）。

操作（修改实时状态）

工具	描述
trigger_workflow	通过名称和 JSON 输入负载触发新的工作流运行。
cancel_runs	根据外部 ID 取消一个或多个运行 / 任务。
replay_runs	根据外部 ID 重放 / 重试一个或多个运行 / 任务。

安全

读取工具（whoami、list_workflows、list_runs、get_run、get_run_logs、list_workers、get_queue_metrics）不会造成破坏。

trigger_workflow、cancel_runs 和 replay_runs 会修改实时状态——它们的描述前缀为 MUTATES LIVE STATE，让 Agent 和用户知道这些工具会影响实际运行。

该令牌授予对整个租户的完全访问权限——请将其视为机密。切勿将其提交到源代码管理中。

开发

pnpm install
pnpm test    # vitest
pnpm build   # tsup -> dist/index.js

TypeScript / ESM，使用 vitest 进行测试。

状态

v0.1.0 — 所有工具均已通过 Hatchet Cloud 验证；通过 HATCHET_API_BASE 也可用于可自托管的实例。trigger_workflow 使用稳定的 /workflow-runs/trigger 端点。