Heliyos

Heliyos MCP 服务

将 AI Agent 连接到 Heliyos，这是一款面向营收的 AI 操作系统。

@heliyos/heliyos-mcp 是适用于 Heliyos 的 Model Context Protocol 服务。它通过 stdio 在你的机器上运行，并使用工作区 API 密钥调用 Heliyos API，因此 Claude Code、Codex、Cursor、VS Code、Antigravity 或任何其他 MCP 客户端中的 Agent 都可以在你的 CRM 中工作。

文档：docs.heliyos.ai/mcp · 安装指南 · 所有工具 · API 参考 · 更新日志

借助它，Agent 可以：

• 查找和更新公司、人员、交易及自定义对象，并为它们添加字段
• 查看记录的时间线、变更历史、电子邮件和会议
• 写入备注和任务，并启动 Heliyos workers 来处理任务
• 列出等待人员审核的内容，并批准或拒绝
• 根据触发器和工具目录创建并配置 workers
• 管理 scouts、查看其信号并维护监视列表
• 查看和编辑知识库，并上传 workers 要读取的文件
• 使用 heliyos_ask 将任务交给 Heliyos 并跟踪运行情况

workers 执行的重要操作仍需在 Heliyos 中等待审核，因此团队始终掌握控制权。

快速开始

1. 在 Heliyos 的 Settings → API keys 下创建 API 密钥（详情见下文）。

2. 将服务添加到你的客户端。以 Claude Code 为例：

   claude mcp add --transport stdio --env HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY --scope user heliyos -- npx -y @heliyos/heliyos-mcp
   

3. 向你的 Agent 提问 “我连接的是哪个 Heliyos 工作区？”。它会调用 heliyos_organization_get 并回答你的工作区名称。

其他客户端的配置方法请参阅安装。

目录

• 快速开始
• 开始之前
• 安装
• 工具超时
• 配置
• 工具
• 安全
• 故障排除
• 开发
• 贡献
• 许可证

开始之前

你需要 Node.js 20 或更高版本（node -v）以及一个 Heliyos API 密钥。

创建密钥：

1. 打开 Heliyos，前往 Settings → API keys（gtm.heliyos.ai/settings/api-keys）。
2. 点击 New key。为密钥取一个便于识别的名称，例如“我笔记本电脑上的 Claude Code”，并按需设置过期日期，然后点击 Create key。
3. 复制密钥。密钥以 heliyos_ 开头，且只会显示一次。如果丢失，请撤销该密钥并创建新密钥。

只有工作区所有者和管理员可以创建密钥。密钥对一个工作区拥有管理员权限，即创建密钥时所在的工作区，不会访问其他任何内容。每个人和每台机器使用一个密钥，这样撤销某个密钥时就不会影响其他密钥。

安装

每个客户端都运行相同的命令 npx -y @heliyos/heliyos-mcp，并通过 HELIYOS_API_KEY 环境变量提供密钥。在下面的代码片段中，将 YOUR_HELIYOS_API_KEY 替换为你的密钥。

Claude Code

一次性安装插件并设置密钥。密钥会存入系统的安全凭据存储区，而不会写入文件；插件还会添加一项技能，教会 Claude 何时使用哪个工具。

claude plugin marketplace add heliyos-ai/heliyos-mcp
claude plugin install heliyos@heliyos --config api_key=YOUR_HELIYOS_API_KEY

如果安装时没有使用 --config，服务器会保持关闭，直到设置密钥：在 Claude Code 中运行 /plugin configure heliyos@heliyos 并输入密钥。之后，/mcp 会列出 heliyos；如果没有，请重启 Claude Code。

或者，只添加 MCP 服务：

claude mcp add --transport stdio --env HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY --scope user heliyos -- npx -y @heliyos/heliyos-mcp

运行 claude mcp list 检查，或在会话中运行 /mcp。

Claude Desktop

打开 Settings → Developer → Edit Config，将服务添加到 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "heliyos": {
      "command": "npx",
      "args": ["-y", "@heliyos/heliyos-mcp"],
      "env": { "HELIYOS_API_KEY": "YOUR_HELIYOS_API_KEY" }
    }
  }
}

此文件会以明文形式存储密钥，请妥善保管。claude.ai 上的自定义连接器以及 Claude 连接器目录中的连接器需要托管（远程）MCP 服务和 OAuth。Heliyos 目前尚未提供此类服务，因此请暂时使用本地客户端。

Codex

将服务添加到 ~/.codex/config.toml：

[mcp_servers.heliyos]
command = "npx"
args = ["-y", "@heliyos/heliyos-mcp"]
env_vars = ["HELIYOS_API_KEY"]
startup_timeout_sec = 30
tool_timeout_sec = 120

env_vars 会从启动 Codex 的 Shell 中传递 HELIYOS_API_KEY，因此请在该 Shell 中导出密钥（例如，在 ~/.zshrc 中）。若要将密钥保存在文件中，请将 env_vars 行替换为末尾的 env 表：

[mcp_servers.heliyos.env]
HELIYOS_API_KEY = "YOUR_HELIYOS_API_KEY"

CLI 可以用一行命令完成相同操作，之后将 tool_timeout_sec = 120 添加到它写入的表中：

codex mcp add heliyos --env HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY -- npx -y @heliyos/heliyos-mcp

Cursor

将 Heliyos 添加到 Cursor

该链接会打开此深层链接，你也可以将其粘贴到浏览器中：

cursor://anysphere.cursor-deeplink/mcp/install?name=heliyos&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBoZWxpeW9zL2hlbGl5b3MtbWNwIl0sImVudiI6eyJIRUxJWU9TX0FQSV9LRVkiOiIke2VudjpIRUxJWU9TX0FQSV9LRVl9In19

它会将以下条目添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "heliyos": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@heliyos/heliyos-mcp"],
      "env": { "HELIYOS_API_KEY": "${env:HELIYOS_API_KEY}" }
    }
  }
}

Cursor 会从自身环境中读取 ${env:HELIYOS_API_KEY}。在 Shell 配置文件中导出此变量，并从该 Shell 启动 Cursor；或者将其值替换为你的密钥。在此代码库中运行 npm run install-links 可再次显示这些链接。

VS Code

在 VS Code 中安装 Heliyos

该链接会打开此深层链接，你也可以将其粘贴到浏览器中：

vscode:mcp/install?%7B%22name%22%3A%22heliyos%22%2C%22inputs%22%3A%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22heliyos-api-key%22%2C%22description%22%3A%22Heliyos%20API%20key%20(Settings%20%E2%86%92%20API%20keys)%22%2C%22password%22%3Atrue%7D%5D%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40heliyos%2Fheliyos-mcp%22%5D%2C%22env%22%3A%7B%22HELIYOS_API_KEY%22%3A%22%24%7Binput%3Aheliyos-api-key%7D%22%7D%7D)%22%2C%22password%22%3Atrue%7D%5D%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40heliyos%2Fmcp%22%5D%2C%22env%22%3A%7B%22HELIYOS_API_KEY%22%3A%22%24%7Binput%3Aheliyos-api-key%7D%22%7D%7D

服务器首次启动时，VS Code 会询问密钥，并将其保存在机密存储区中。若要手动设置，请将以下内容添加到项目中的 .vscode/mcp.json，或添加到用户级 mcp.json（MCP: Open User Configuration）：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "heliyos-api-key",
      "description": "Heliyos API key (Settings → API keys)",
      "password": true
    }
  ],
  "servers": {
    "heliyos": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@heliyos/heliyos-mcp"],
      "env": { "HELIYOS_API_KEY": "${input:heliyos-api-key}" }
    }
  }
}

Antigravity

在 Agent 面板中，打开 … → MCP Servers → Manage MCP Servers → View raw config，或直接编辑 ~/.gemini/config/mcp_config.json（单个项目则编辑 .agents/mcp_config.json）：

{
  "mcpServers": {
    "heliyos": {
      "command": "npx",
      "args": ["-y", "@heliyos/heliyos-mcp"],
      "env": { "HELIYOS_API_KEY": "YOUR_HELIYOS_API_KEY" }
    }
  }
}

其他客户端

使用环境变量中的密钥，通过标准输入输出运行此软件包：

HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY npx -y @heliyos/heliyos-mcp

此仓库还提供便携式 Agent Plugins 清单（plugin.json 和 mcp.json），供从 Git 仓库安装插件的客户端使用。清单不包含密钥，因此请在客户端启动服务时使用的环境中设置 HELIYOS_API_KEY。此服务在 MCP Registry 中的名称为 ai.heliyos/heliyos-mcp。

工具超时

heliyos_ask 最多等待 Heliyos 90 秒，因此请为工具调用预留至少 120 秒。

客户端	设置
Codex	在 [mcp_servers.heliyos] 表中设置 tool_timeout_sec = 120（默认值为 60）。如果通过市场安装为插件，Codex 会保留 60 秒的默认值，因为插件的 .mcp.json 无法包含 tool_timeout_sec，因此耗时较长的 heliyos_ask 会在 60 秒后停止；如需设置为 120 秒，请使用上面的 config.toml 配置。
Claude Code	默认值足够长。如果设置了 MCP_TOOL_TIMEOUT，请将其设为 120000 或更高，例如 MCP_TOOL_TIMEOUT=120000 claude。
Claude Desktop	没有已记录的设置。
Cursor	没有已记录的工具超时设置。
VS Code	没有已记录的工具超时设置。
Antigravity	没有已记录的工具超时设置。

客户端提前终止调用时，Heliyos 中的运行仍会继续。使用 heliyos_runs_list 查找该运行，并通过 heliyos_runs_get 和 wait: true 跟进；每次调用最多等待 30 秒。

遇到速率限制的请求（HTTP 429）会在 Retry-After 指定的延迟后重试一次，延迟最长为 30 秒，因此触发限流的 heliyos_ask 可能需要约 125 秒。如果接近限流时出现超时，请将超时设为 150 秒。

配置

变量	必填	默认值	功能
HELIYOS_API_KEY	是	无	你的 Heliyos API 密钥。必须以 heliyos_ 开头。
HELIYOS_BASE_URL	否	https://api-prod.heliyos.ai	要调用的 Heliyos API。必须使用 https；仅 localhost 支持普通 http。
HELIYOS_MCP_EXPERIMENTAL	否	关闭	设置为 1、true、yes 或 on 可启用下方标记为实验性的工具。

此服务还提供一个资源模板 heliyos://records/{id}，用于以 JSON 格式返回一条记录；以及两个提示词：prepare_account_review（适用于一家公司）和 daily_pipeline_summary。

工具

每个工具都以 heliyos_<resource>_<verb> 命名，并声明其操作是读取、写入还是删除，因此客户端可以在更改任何内容前征求确认。读取操作接受 response_format（concise 或 detailed），列表操作接受 limit 和 cursor。

默认提供 73 个工具，设置 HELIYOS_MCP_EXPERIMENTAL=1 后还会增加 4 个。操作类型分为读取（不做更改）、写入（创建或更新）或破坏性操作（删除或移除）。

记录

工具	功能	类型
heliyos_records_list	列出记录	read
heliyos_records_get	获取一条记录	read
heliyos_records_create	创建一条记录	write
heliyos_records_update	更新一条记录	write
heliyos_records_delete	删除记录	destructive
heliyos_records_lookup	按名称查找记录	read
heliyos_records_enrich	丰富人员信息（实验性）	write

时间线和活动

工具	功能	类型
heliyos_records_timeline	读取记录的时间线	read
heliyos_records_events	读取记录的变更历史	read
heliyos_interactions_list	列出电子邮件和会议	read
heliyos_interactions_get	获取一封电子邮件或一场会议	read

工作区、对象和字段

工具	功能	类型
heliyos_organization_get	获取工作区	读取
heliyos_objects_list	列出对象	读取
heliyos_objects_get	获取对象的字段	读取
heliyos_objects_create	创建自定义对象（实验性）	写入
heliyos_objects_update	重命名对象或修改对象描述（实验性）	写入
heliyos_objects_delete	删除自定义对象（实验性）	破坏性
heliyos_fields_create	向对象添加字段	写入
heliyos_fields_update	修改字段	破坏性
heliyos_fields_delete	删除字段	破坏性

备注

工具	功能	类型
heliyos_notes_list	列出备注	读取
heliyos_notes_get	获取备注	读取
heliyos_notes_create	创建备注	写入
heliyos_notes_update	更新备注	写入
heliyos_notes_delete	删除备注	破坏性

任务

工具	功能	类型
heliyos_tasks_list	列出任务	读取
heliyos_tasks_get	获取任务	读取
heliyos_tasks_events	读取任务活动记录	读取
heliyos_tasks_create	创建任务	写入
heliyos_tasks_update	更新任务	写入
heliyos_tasks_delete	删除任务	破坏性
heliyos_tasks_run	在任务上运行工作者	破坏性

Scout 和信号

工具	功能	类型
heliyos_scouts_list	列出 Scout	读取
heliyos_scouts_get	获取 Scout	读取
heliyos_scouts_create	创建 Scout	写入
heliyos_scouts_update	更新 Scout	写入
heliyos_scouts_delete	删除 Scout	破坏性
heliyos_companies_scouts_list	列出公司的 Scout	读取
heliyos_companies_scouts_add	向公司添加 Scout	写入
heliyos_companies_scouts_remove	移除公司的 Scout	破坏性
heliyos_signals_list	列出信号	读取
heliyos_signals_mark_read	将信号标记为已读	写入

Ask、运行和审核

工具	功能	类型
heliyos_ask	向 Heliyos 提问	破坏性
heliyos_runs_get	获取一次运行	读取
heliyos_runs_list	列出运行	读取
heliyos_reviews_list	列出审核	读取
heliyos_reviews_get	获取审核	读取
heliyos_reviews_decide	批准或拒绝审核	破坏性

工作者、触发器和工具

工具	功能	类型
heliyos_workers_list	列出工作者	读取
heliyos_workers_get	获取工作者	读取
heliyos_workers_create	创建工作者	写入
heliyos_workers_update	更新工作者	写入
heliyos_workers_delete	删除工作者	破坏性
heliyos_triggers_list	列出工作者触发器	读取
heliyos_workers_tools_list	列出工作者可使用的工具	读取

知识库和文件

工具	功能	类型
heliyos_knowledge_get	读取知识库	读取
heliyos_knowledge_update	更新知识库	写入
heliyos_knowledge_entries_set	添加或修改知识条目	写入
heliyos_knowledge_entries_delete	删除知识条目	破坏性
heliyos_files_list	列出文件	读取
heliyos_files_get	获取文件	读取
heliyos_files_upload	上传文件	写入
heliyos_files_delete	删除文件	破坏性

关注列表

工具	功能	类型
heliyos_watchlist_get	获取关注列表	读取
heliyos_companies_watch	关注一家公司	写入
heliyos_companies_unwatch	取消关注一家公司	破坏性

标签

工具	功能	类型
heliyos_labels_list	列出标签组	读取
heliyos_labels_create	创建标签组	写入
heliyos_labels_update	更新标签组	破坏性操作
heliyos_labels_delete	删除标签组	破坏性操作

团队

工具	功能	类型
heliyos_team_members_list	列出团队成员	读取
heliyos_team_members_invite	邀请团队成员	写入
heliyos_team_members_remove	移除团队成员	破坏性操作
heliyos_team_members_change_role	更改团队成员的角色	写入

通知设置

工具	功能	类型
heliyos_notification_settings_get	获取通知设置	读取
heliyos_notification_settings_update	更新通知设置	写入

用量

工具	功能	类型
heliyos_usage_get	获取额度用量	读取

安全

• 密钥保留在你的设备上。 服务从环境中读取密钥，并仅将其作为 bearer token 通过 https 发送到 Heliyos API（HELIYOS_BASE_URL）。如果基础 URL 不是 https（localhost 除外），服务会拒绝使用。
• 文件上传不会携带密钥。 文件内容会发送到一个短期有效的签名存储 URL，且该请求不会携带你的密钥。
• 不收集遥测数据。 服务不会向其他任何地方发送数据，也不会保留日志。诊断信息会输出到客户端的 stderr，错误消息中的密钥会被移除。
• 速率限制。 API 对每个密钥和每个 IP 地址均限制为每分钟 60 次请求。当 API 返回 429 时，服务会等待 Retry-After 指定的时间，然后重试一次。
• 最小访问权限。 一个密钥在一个工作区中拥有管理员权限。请为密钥设置有效期，每个人和每台设备各使用一个密钥；不再需要时，请在 设置 → API 密钥 中撤销。
• 破坏性工具会明确标记。 删除和移除操作会标注为破坏性操作，Agent 技能会指示 Agent 先确认再执行。

请通过 GitHub 安全公告 私下报告安全问题，不要在公开议题中报告。

故障排查

你看到的情况	处理方法
heliyos-mcp: Set HELIYOS_API_KEY to a Heliyos API key	客户端未传入密钥。检查 env 块，或确认启动客户端的 shell 已导出该变量。
HELIYOS_API_KEY does not look like a Heliyos API key	该值不是 Heliyos 密钥。密钥以 heliyos_ 开头。请重新复制或创建新密钥。
UNAUTHENTICATED	密钥已撤销、已过期或输入错误。请在 Settings → API keys 中创建新密钥。
FORBIDDEN_ACTION	工作区套餐或账单状态不允许执行此操作，或者 API 密钥无法使用此操作。
RATE_LIMITED	请求速率超过每分钟 60 次。请等待一分钟，并优先使用列表调用，而不是多次单项获取。
heliyos_ask 超时	请延长客户端的工具超时时间（参见工具超时时间）。运行会继续；后续可使用 heliyos_runs_get 查询。
服务首次启动时显示“connecting”	首次运行 npx -y @heliyos/heliyos-mcp 会下载软件包，在网速较慢时可能需要 20 到 30 秒，超过客户端的启动超时时间。请先在终端运行一次 npx -y @heliyos/heliyos-mcp --version 预热缓存，然后重新连接；之后启动大约只需一秒。或者延长超时时间（Codex 使用 startup_timeout_sec，Claude Code 使用 MCP_TIMEOUT=60000）。
Node 16.x is too old 或工具报错 fetch is not defined	客户端使用旧版 Node 启动了 npx，通常是因为版本管理器的默认版本过旧。服务需要 Node 20 或更高版本，并会在找到的最新兼容 Node 版本上自行重启（nvm、fnm、n、Volta、Homebrew、PATH）；提示信息会指出使用的是哪个版本。如果没有找到兼容版本，请安装 Node 20+，或运行 nvm install 20 && nvm alias default 20，然后重启客户端。从程序坞打开的应用可能找不到 npx；请使用 which npx 获取其完整路径。
缺少实验性工具	设置 HELIYOS_MCP_EXPERIMENTAL=1 并重启客户端。

仍未解决？请在 github.com/heliyos-ai/heliyos-mcp/issues 提交问题。切勿粘贴你的密钥。

开发

要求：Node.js 20 或更高版本，以及 npm。其他内容都是开发依赖。

git clone https://github.com/heliyos-ai/heliyos-mcp.git
cd heliyos-mcp
npm ci
npm test                  # unit tests with a mocked Heliyos API
npm run typecheck
npm run build             # codegen, then tsc into dist/
npm run readme:tools      # regenerate the tool table above
npm run install-links     # print the Cursor and VS Code install links
npm run prepublish:check  # manifests, versions and package contents
HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY npm run smoke   # read-only checks against a real workspace

若要在客户端中运行本地构建版本，而非已发布的软件包，请将客户端指向 dist/src/bin/stdio.js：

claude mcp add --transport stdio --env HELIYOS_API_KEY=YOUR_HELIYOS_API_KEY --scope user heliyos-dev -- node /path/to/heliyos-mcp/dist/src/bin/stdio.js

构建方式

• src/client/openapi/ 存放 Heliyos API 的 OpenAPI 文档副本。npm run codegen 会将其转换为带类型的操作表（src/client/generated.ts），并附带 zod 模式，以便在发送每个请求前进行验证。
• src/tools/ 为每种资源定义一个文件。每个工具都会声明其输入和输出模式、注释（读取、写入或破坏性操作），以及一个调用一个或两个 API 操作并生成简短文本和 structuredContent 的处理程序。
• tests/ 使用 msw 对模拟 API 运行每个工具。快照测试会固定公开的工具契约（名称、注释、输入键），因此意外更改会导致构建失败。
• skills/heliyos/SKILL.md 随 Claude Code 插件一同发布，并指导 Agent 何时使用哪个工具。

更新 API 客户端

Heliyos API 变更时，请保存新的 OpenAPI 文档并重新同步：

curl -s https://api-prod.heliyos.ai/v1/platform/openapi.json -o /tmp/platform.json
curl -s https://api-prod.heliyos.ai/v1/auth/openapi.json -o /tmp/auth.json
HELIYOS_PLATFORM_OPENAPI=/tmp/platform.json HELIYOS_AUTH_OPENAPI=/tmp/auth.json npm run sync-openapi
npm run codegen && npm test

设置这两个变量后，npm run prepublish:check 和漂移测试也会拒绝与当前内容不匹配的捆绑副本。

发布

每次推送到 main 时，GitHub Actions 都会发布版本（.github/workflows/publish-package.yml）：

1. CI 会构建、测试并检查软件包和清单。
2. 如果 package.json 中的版本已发布到 npm，工作流会通过 node scripts/set-version.mjs 增加补丁版本号。该脚本会确保 package.json、锁定文件、server.json、每个插件清单和 src/version.ts 的版本一致，并提交此次版本更新。
3. 工作流会通过 npm 可信发布机制发布到 npm 并提供来源证明（不会在任何地方存储令牌），等待该版本上线，然后在配置了 MCP_PRIVATE_KEY 密钥时，将 server.json 发布到 MCP 注册表。

如需发布指定版本，请运行 node scripts/set-version.mjs 1.2.0，然后提交并推送到 main。一次性仓库设置请参阅 CONTRIBUTING.md。

参与贡献

欢迎提交问题和拉取请求。请阅读 CONTRIBUTING.md，了解工作流、编码规范以及如何添加工具；如需了解如何报告漏洞，请阅读 SECURITY.md。参与即表示你同意遵守行为准则。

许可证

MIT