krova

@krovacloud/mcp

适用于 Krova Cloud 的 MCP 服务 — 让 Claude、Cursor 和任何 MCP 客户端通过自然语言创建和管理 Cubes（Firecracker 微型虚拟机）。

一个 Model Context Protocol 服务，将 Krova Cloud 封装为一组 AI Agent 可调用的工具。让 Claude 帮你“在美国区域启动一个 2 vCPU 的 Ubuntu Cube”“列出我正在运行的 Cubes”或“关闭闲置的 Cube”，它便会为你调用 Krova Cloud API。

这是基于官方 @krovacloud/sdk 构建的轻量、完全类型化的桥接层：每项 Krova Cloud 操作都是一个 MCP 工具，具有经过验证的输入架构，并使用你的 API 密钥进行身份验证。

快速入门

最快的试用方式 — 无需安装或克隆：

KROVA_API_KEY=kro_... npx -y @krovacloud/mcp

此服务通过 stdio 使用 MCP，因此通常无需手动运行 — MCP 客户端会使用该命令启动它。请在下方选择你的客户端。

客户端配置

所有客户端都使用相同的启动命令（npx -y @krovacloud/mcp）和相同的环境变量。至少设置 KROVA_API_KEY；如果希望 Cube 工具默认使用某个 Space，也请设置 KROVA_SPACE_ID。

Claude Desktop

编辑 claude_desktop_config.json（Settings → Developer → Edit Config，或 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json / Windows 上的 %APPDATA%\Claude\claude_desktop_config.json），并添加：

{
  "mcpServers": {
    "krova": {
      "command": "npx",
      "args": ["-y", "@krovacloud/mcp"],
      "env": {
        "KROVA_API_KEY": "kro_your_api_key_here",
        "KROVA_SPACE_ID": "space_optional_default"
      }
    }
  }
}

重启 Claude Desktop。Krova Cloud 工具会显示在工具（🔨）菜单中。

Claude Code

使用一条命令添加服务：

claude mcp add krova \
  --env KROVA_API_KEY=kro_your_api_key_here \
  --env KROVA_SPACE_ID=space_optional_default \
  -- npx -y @krovacloud/mcp

或者将其添加到项目根目录下的 .mcp.json（提交到代码库，与团队共享）：

{
  "mcpServers": {
    "krova": {
      "command": "npx",
      "args": ["-y", "@krovacloud/mcp"],
      "env": {
        "KROVA_API_KEY": "kro_your_api_key_here",
        "KROVA_SPACE_ID": "space_optional_default"
      }
    }
  }
}

使用 claude mcp list 验证。

Cursor

在项目中创建 .cursor/mcp.json（或在 ~/.cursor/mcp.json 中创建，以供所有项目使用）：

{
  "mcpServers": {
    "krova": {
      "command": "npx",
      "args": ["-y", "@krovacloud/mcp"],
      "env": {
        "KROVA_API_KEY": "kro_your_api_key_here",
        "KROVA_SPACE_ID": "space_optional_default"
      }
    }
  }
}

然后在 Cursor Settings → MCP 中启用 krova 服务。

任何其他 MCP 客户端

任何支持通过 stdio 使用 MCP 的客户端都可以使用 — 设置好环境变量后，启动 npx -y @krovacloud/mcp 即可。上述配置格式可用于 VS Code（Copilot）、Windsurf、Zed，以及基于 MCP SDK 构建的自定义 Agent。

配置

此服务完全通过环境变量进行配置：

变量	必填	描述
KROVA_API_KEY	是	你的 Krova Cloud API 密钥（kro_...）。作用域限定为一个 Space；继承创建该密钥的成员权限。
KROVA_SPACE_ID	否	默认 Space ID，这样 Cube 工具就可以省略 spaceId。
KROVA_BASE_URL	否	覆盖 API 基础 URL（默认为 Krova Cloud 生产环境 API）。

工具

所有 37 个工具及其参数和功能。设置 KROVA_SPACE_ID 后，每个工具的 spaceId 参数均可选。

工具	参数	描述
list_cubes	spaceId?	列出某个 Space 中的所有 Cube（Firecracker microVM）。
get_cube	spaceId?、cubeId	按 ID 获取单个 Cube 的详细信息。
get_cube_ssh	spaceId?、cubeId	获取 SSH 的主机、端口、登录用户和固定的主机密钥。host 是 Cube 自身稳定的 SSH 主机名，不是服务器的 IP；迁移到其他服务器后仍会保留。只有当 Cube 尚无 DNS 记录时，才会回退为服务器的公网 IPv4 地址。请调用此工具，而不是猜测用户名——较新的 Cube 使用 ubuntu/debian，较旧的使用 root，且无法根据镜像 ID 推断。
create_cube	spaceId?、name、image、vcpu、ramGb、diskGb、sshPublicKey、region?、userData?	配置新的 Cube。此操作为异步操作——返回的 Cube 初始状态为 pending。会产生费用。具有破坏性。
power_off_cube	spaceId?、cubeId	关闭正在运行的 Cube（释放计算资源和主机 RAM，但保留磁盘）。此操作为异步操作。
wake_cube	spaceId?、cubeId	启动已停止的 Cube。此操作为异步操作。
restart_cube	spaceId?、cubeId	重启正在运行的 Cube。这是一次冷重启——Cube 会使用主机当前的内核启动，因此这是获取更新后的客户机内核的唯一方式（在 Cube 内发出 reboot 无法做到这一点，且不会报告错误）。磁盘状态会保留。此操作为异步操作；如果同时发起另一次重启，请求会被拒绝，而不会排队。
delete_cube	spaceId?、cubeId	删除 Cube。此操作为异步操作——删除请求会进入队列。具有破坏性。
protect_cube	spaceId?、cubeId	开启终止保护：在关闭保护之前，delete_cube 会返回 409 错误。仍可执行关机、唤醒、重启、快照和恢复操作。此操作具备幂等性。
unprotect_cube	spaceId?、cubeId	关闭终止保护，以便再次使用 delete_cube。此操作具备幂等性。
list_regions	—	列出有可用容量的区域。
list_images	—	列出可用于新建 Cube 的操作系统镜像。
get_pricing	—	获取各资源的小时费率和卷定价档位。
list_domains	spaceId?、cubeId	列出附加到 Cube 的自定义域名。
get_domain_records	spaceId?、cubeId、mappingId	列出域名所需的 DNS 记录，并逐条检查实时 DNS——missing 表示尚未发布（用户尚未创建这些记录时属于预期情况，并非错误）；找到所有记录后，summary.complete 会变为 true。会执行真实的 DNS 查询；有速率限制。
create_domain	spaceId?、cubeId、domain、port、originScheme?、proxyProtocol?、confirmMixedProxyProtocol?	将自定义域名附加到 Cube。返回域名以及需要发布的 DNS 记录——请原样转发这些记录。
update_domain	spaceId?、cubeId、mappingId、originScheme?、proxyProtocol?、confirmMixedProxyProtocol?	更改域名的代理设置：源站协议，以及用于在每个连接到 Cube 的连接上标识访客的 PROXY 协议标头（v1、v2 或 off）。至少传入一个参数；未传入的参数会保留原值。
delete_domain	spaceId?、cubeId、mappingId	从 Cube 移除自定义域名。具有破坏性。
list_snapshots	spaceId?、cubeId	列出 Cube 的磁盘快照。
create_snapshot	spaceId?、cubeId、name?	为 Cube 的磁盘创建快照。此操作为异步操作。
delete_snapshot	spaceId?、cubeId、snapshotId	删除快照。具有破坏性。
restore_cube	spaceId?、cubeId、snapshotId	从快照恢复 Cube 的磁盘——会替换磁盘。具有破坏性。
list_backups	spaceId?	按时间从新到旧列出该空间的备份。其他空间与此空间共享的副本会设置 sharedFromBackupId。
get_backup	spaceId?、backupId	获取单个备份。
share_backup	spaceId?、backupId、destinationSpaceId	向另一个空间提供备份副本。在目标空间于 48 小时内接受之前，不会复制任何内容；接受后，该副本归目标空间所有，费用也由其承担。具有破坏性（会将磁盘副本交给另一个空间）。
list_backup_shares	spaceId?	列出该空间收到的（incoming）和发出的（outgoing）待处理共享。
accept_backup_share	spaceId?、shareId	接受与该空间共享的备份。从现在起，该空间需要为其副本支付备份存储费用。具有破坏性（会产生费用）。
decline_backup_share	spaceId?、shareId	拒绝与该空间共享的备份。不会复制任何内容。
cancel_backup_share	spaceId?、shareId	撤回该空间发出的待处理共享。
list_tcp_mappings	spaceId?、cubeId	列出 Cube 的 TCP 端口映射。
create_tcp_mapping	spaceId?、cubeId、cubePort、whitelistedIps?	在主机上公开 Cube 的 TCP 端口。仍接受已弃用的别名 whitelistIps。
delete_tcp_mapping	spaceId?、cubeId、mappingId	移除 TCP 端口映射。具有破坏性。
list_webhooks	spaceId?	列出该空间中的 webhook 端点、对应事件以及每个端点是否已启用。
get_webhook	spaceId?、endpointId	获取单个 webhook 端点。此处不会返回签名密钥。
create_webhook	spaceId?、url、events、description?	创建 webhook 端点。签名密钥仅在此响应中返回；请立即保存。
delete_webhook	spaceId?、endpointId	删除 webhook 端点及其投递历史记录。具有破坏性。
list_webhook_deliveries	spaceId?、endpointId、limit?	列出某个端点最近 30 天的投递尝试记录，按时间从新到旧排列（最多 100 条）。
每个工具都会声明 MCP 注解，以便客户端以适当方式处理：十六个读取工具（list_cubes、get_cube、get_cube_ssh、list_regions、list_images、get_pricing、list_domains、get_domain_records、list_snapshots、list_backups、get_backup、list_backup_shares、list_tcp_mappings、list_webhooks、get_webhook、list_webhook_deliveries）都标记为只读，而九个破坏性工具（create_cube、delete_cube、delete_domain、delete_snapshot、restore_cube、share_backup、accept_backup_share、delete_tcp_mapping、delete_webhook）都标记为破坏性。update_domain 会修改数据，但具有幂等性且可撤销，因此不属于破坏性工具。大多数 MCP 客户端会在运行破坏性工具前显示确认提示——请保留此确认，因为由不可信内容驱动的大模型可能会被诱导调用这类工具。

备份工具要求 API 密钥所属成员拥有 Backups 权限：读取需要 View Backups，共享和响应共享请求需要 Manage Backups。我们特意没有提供下载工具：下载链接无需进一步身份验证即可获取整个磁盘，因此模型的对话并不适合执行此操作。请使用命令行中的 krova backups download。

create_cube 参数

参数	类型	说明
name	string	易于辨认的 Cube 名称。
image	string	OS 镜像标识 — 参见 list_images。ubuntu-24.04、ubuntu-24.04-docker、debian-13 或 debian-13-docker。
region	string?	可选的区域标识 — 参见 list_regions。省略此项可由 Krova Cloud 自动选择有容量的区域。
vcpu	integer	虚拟 CPU 数量。每个空间的默认上限为 16（可为你的空间提高上限）。
ramGb	integer	RAM 容量，以整 GiB 为单位。每个空间的默认上限为 32 GB（可为你的空间提高上限）。
diskGb	integer	磁盘容量，以 GiB 为单位 — 最小为 10，增量为 5。每个空间的默认上限为 100 GB（可为你的空间提高上限）。
sshPublicKey	string	启动时写入 /root/.ssh/authorized_keys（ssh-ed25519、ssh-rsa、ecdsa-sha2-* 等）。API 要求必填。
userData	string?	可选的 cloud-init 脚本（强制限制为最多 16 KiB）。

成功调用会以文本形式返回 API 的 JSON 响应；API 错误会作为 MCP 错误结果返回，其中包含 HTTP 状态码、API 消息，以及可用时的请求 ID。

身份验证

你需要一个 Krova Cloud API 密钥。请在 Krova Cloud 控制面板的 Space 设置中创建密钥 — 密钥按 Space 限定范围，继承创建密钥的成员权限，格式类似 kro_...。

切勿提交密钥，或将其粘贴到日志、问题或聊天中。如果你认为某个密钥已经泄露，请立即轮换。参见 SECURITY.md。

要求

• Node.js ≥ 18（底层 SDK 使用全局 fetch）。
• 支持 MCP 的客户端（Claude Desktop、Claude Code、Cursor 或你自己的 Agent）。

相关软件包

属于 Krova Cloud 开发者工具包：

• @krovacloud/sdk — 本服务基于此官方 TypeScript SDK 构建。
• Krova Cloud 文档和控制面板 — 托管的 API 文档、OpenAPI 规范，以及获取 API 密钥的入口。

贡献

参见 CONTRIBUTING.md。src/tools.ts 中的工具注册表是唯一可信来源 — 添加 defineTool(...)，在 tests/ 中为其编写测试，并更新上方的表格。提交 PR 前，请运行 pnpm typecheck、pnpm test 和 pnpm build。

许可证

MIT © 2026 Krova Inc.

发布到官方 MCP Registry

此服务已列入 cloud.krova/mcp。 CI 会在每次发布时自动重新发布——请参阅 .github/workflows/ci-release.yml 中的 Publish MCP server to the official registry 步骤。

它需要一个仓库密钥 MCP_PRIVATE_KEY。 在配置该密钥之前，此步骤会记录跳过信息并且不执行任何操作，因此不会阻塞发布。

该值是 Ed25519 原始私钥的十六进制编码，来源于其公钥部分已作为 TXT 记录发布在 krova.cloud 顶级域名上的密钥：

openssl pkey -in key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n' | pbcopy

⚠️ 请将它通过管道传给 pbcopy，不要在终端中查看。该命令不会输出结尾换行符，因此 zsh 会显示一个结尾的 %——如果凭眼睛复制时把它也复制进去，就会写入密钥，导致发布程序报错： invalid hex private key format: ... invalid byte: U+0025 '%'。CI 现在会剥除非十六进制字符并检查长度是否为 64，因此不会再因此出错。

⛔ 正是命名空间导致必须配置密钥。 mcp-publisher login github-oidc 无需密钥，但只会授予 io.github.<org>/*——使用它就意味着放弃 cloud.krova/mcp、以新名称重新发布，并使当前条目失效。选择品牌命名空间是经过慎重考虑的。

手动运行

pnpm publish:mcp-registry --dry-run   # derives the version, writes and publishes nothing
pnpm publish:mcp-registry

脚本从 npm 读取版本，绝不会从 server.json 读取；如果 Registry 已提供该版本，脚本会提前退出。这是有意为之：存储的版本号不可信，因为 release.mjs 会根据 npm 上的最新版本递增补丁版本号，CI 不会将递增后的版本号提交回仓库，而且 server.json 不在软件包的 files 列表中，因此也不会被打包到 tarball 中。发布过时版本会静默失败——Registry 只检查该版本是否存在于 npm 上且带有 mcpName 标记，不检查它是否为最新版本。