hermai-mcp

Hermai MCP

专为 Hermai 打造的 Model Context Protocol 服务。

当 Agent 运行时支持 MCP，且需要将 Hermai 作为原生工具调用时，请使用此软件包。Hermai CLI 是供人工操作人员使用的独立工具，MCP 无需依赖它。

安装

直接使用 npx 运行：

npx -y hermai-mcp

或全局安装：

npm install -g hermai-mcp
hermai-mcp

MCP 客户端配置

{
  "mcpServers": {
    "hermai": {
      "command": "npx",
      "args": ["-y", "hermai-mcp"]
    }
  }
}

可选环境变量：

• HERMAI_API_BASE 或 HERMAI_PLATFORM_URL：API 基础 URL。默认为 https://api.hermai.ai。
• HERMAI_API_KEY 或 HERMAI_PLATFORM_KEY：用于访问经过身份验证的 Hermai API 的 API 密钥。公开的架构查询和架构请求提交无需密钥。设置密钥后，还可使用 fetch_schema 执行工具（见下文）。
• HERMAI_FETCH_TIMEOUT_MS：fetch_schema 的请求超时时间。默认为 120000（托管获取通道可能运行数十秒）。

Claude Code 工作流

当你希望 Claude Code 发现架构、检查可用工作流并发起经过身份验证的读取请求时，请使用本地 MCP 服务。Hermai MCP 是本地 stdio 服务，并非远程 Claude 连接器。

安装 Claude Code，然后将 Hermai 添加到你的个人 Claude Code 配置中：

export HERMAI_API_KEY='hm_sk_...'
claude mcp add --scope user hermai -e HERMAI_API_KEY="$HERMAI_API_KEY" -- npx -y hermai-mcp
unset HERMAI_API_KEY

密钥会保存在你的本地 Claude Code 配置中。不要将此命令放入代码仓库、共享的 shell 历史记录或项目范围的 MCP 配置中。

确认 Claude Code 可以看到该服务：

claude mcp list

然后启动 Claude Code，并使用以下两步请求：

Use lookup_schema to find a verified public Hermai schema for [the source and task].
Before making a fetch, show me the site, endpoint, required parameters, and whether
the result can be retrieved with fetch_schema.

批准选定的工作流后：

Use fetch_schema with the site, endpoint, and parameters we selected. Return a short
summary of the records, then show credits_used, credits_remaining, and cached from
the response metadata.

lookup_schema 无需密钥即可安全使用。只有配置了密钥时，才会显示 fetch_schema。它通过 Hermai Cloud 读取数据，成功请求会消耗额度。不要向服务提供浏览器 Cookie、Bearer 令牌，也不要提交会更改其他服务数据的请求。

完整的验证清单和预期故障处理流程，请参阅Claude Code 指南。

工具

始终可用（无需密钥）：

• lookup_schema — 按域、任务、类别或验证状态搜索 Hermai 架构。
• list_public_schemas — 分页浏览公开架构。
• submit_schema_request — 为脆弱的浏览器/API 工作流提交六字段请求。
• classify_browser_workflow — 在本地判定工作流对应的是直接 API、隐藏端点、仅限浏览器，还是所有者/身份验证工作。
• check_schema_request_status — 查询架构请求状态。

仅在设置了 HERMAI_API_KEY（或 HERMAI_PLATFORM_KEY）时可用：

• fetch_schema — 通过托管的 /v1/fetch 执行已注册的架构并返回实时数据。**仅检索数据，不会修改数据；并且会消耗 Hermai 额度：标准调用消耗 1 个额度，部分高成本网站消耗 5 个额度；仅对成功调用计费。**输入：site、endpoint（请先通过 lookup_schema 解析这两项；endpoint 区分大小写）以及可选的 params。结果包含上游 data 和元数据摘要（credits_used、credits_remaining、latency_ms、cached）；发生故障时会返回 API 的 code 和 message，若额度不足时的 402 错误提供升级途径，还会返回 upgrade_to 和 upgrade_url。仅用于读取工作流——写入或经所有者批准的工作流应通过 Hermai CLI 的签名写入流程处理，而不要使用此工具。

切勿通过架构请求提交 Cookie、Bearer 令牌、API 密钥、会话 ID 或私人会话数据。