kilawatt-mcp-server

Kilawatt Cloud MCP 服务

用于从 Kilawatt Cloud 请求 GPU 计算容量的 Model Context Protocol（MCP）服务，支持账户付款和 x402 付款选项。

此服务会调用 Kilawatt 的真实网关。 每个响应都是 Kilawatt 公共 API 或 x402 端点返回的实际 HTTP 结果，不存在虚构响应。

目录

• 适用对象
• 端点
• 安装
• 配置
• 与 Claude Desktop / Cursor 搭配使用
• 运行服务
• 可用工具
• 错误处理
• 链接
• 许可证

适用对象

• goose（分步指南：docs/GOOSE_TUTORIAL.md）
• Claude Desktop
• Cursor
• LangChain 和 LangGraph（示例）
• CrewAI（示例）
• SkyPilot（示例）
• Node.js 客户端（示例）
• MCP Python SDK（示例）

所有示例都仅用于获取报价。请参阅 examples/README.md。

客户端设置步骤见 docs/clients.md。

端点

默认端点是 Kilawatt Cloud 的网关：https://www.kilawattcloud.dev/api/public/v1。使用 KILAWATT_BASE_URL 环境变量进行更改。

发现和恢复工具（get_capacity、get_platform_status、get_pricing、get_resume_info 和 resume_job）使用的是站点根地址：https://www.kilawattcloud.dev。使用可选的 KILAWATT_SITE_URL 环境变量进行更改。末尾的斜杠会被移除。

变量	使用方	默认值
KILAWATT_BASE_URL	deploy_gpu_node	https://www.kilawattcloud.dev/api/public/v1
KILAWATT_SITE_URL	get_capacity、get_platform_status、get_pricing、get_resume_info、resume_job	https://www.kilawattcloud.dev

安装

通过 npx 安装并运行：

npx -y kilawatt-mcp-server

配置

设置 Kilawatt API 密钥，以使用 deploy_gpu_node、get_resume_info 或 resume_job。启动服务、使用 x402 工具，或使用 get_capacity、get_platform_status 和 get_pricing 均无需设置密钥：

export KILAWATT_API_KEY=kw_live_YOUR_KEY_HERE

API 密钥必须以 kw_live_ 开头。API 密钥通过你的 Kilawatt Cloud 账户签发。如果你尚无生成密钥的权限，请联系 [email protected] 获取帮助。

与 Claude Desktop / Cursor 搭配使用

将此配置添加到 MCP 客户端设置中：

{
  "mcpServers": {
    "kilawatt": {
      "command": "npx",
      "args": ["-y", "kilawatt-mcp-server"],
      "env": {
        "KILAWATT_API_KEY": "kw_live_YOUR_KEY_HERE"
      }
    }
  }
}

使用 deploy_gpu_node 时，请将 kw_live_YOUR_KEY_HERE 替换为你的 Kilawatt API 密钥。仅使用 x402 时，请省略 KILAWATT_API_KEY。

使用 goose？请参阅 GOOSE.md。

运行服务

启动 MCP 服务：

npm start

或直接运行：

node index.js

服务通过标准输入/输出通道接收来自 Agent 的 MCP 请求。

可用工具

该服务提供九个工具：deploy_gpu_node、x402_quote、x402_run_job、x402_job_status、get_capacity、get_platform_status、get_pricing、get_resume_info 和 resume_job。

deploy_gpu_node

在 Kilawatt Cloud 上配置真实 GPU 算力。这会启动一台实际机器，并从调用者的 Kilawatt 钱包扣费。将 dry_run: true 设为仅检查价格和路由，不配置资源也不扣费。需要 KILAWATT_API_KEY。

参数	类型	必填	默认值	允许的值	描述
gpu_type	字符串	否	nvidia-h100	最长 64 个字符的任意非空字符串（本地不会检查枚举值）	GPU 型号标识符；网关决定接受哪些值
card_count	整数	否	1	1 至 64	GPU 数量
duration_seconds	数字	否	600	1 至 86400	节点所需时长。预先计费。
routing_policy	字符串	否	lowest_cost	lowest_cost、lowest_latency、zero_quota	智能订单路由器选择节点的方式
dry_run	布尔值	否	false	true、false	仅定价和预授权

{
  "name": "deploy_gpu_node",
  "arguments": { "card_count": 2, "duration_seconds": 1800, "dry_run": true }
}

x402_quote

获取 GPU 作业的当前价格和 Base USDC 付款详情，无需付款。

参数	类型	必填	默认值	允许的值	描述
gpu_type	字符串	否	nvidia-h100	nvidia-b300、nvidia-b200、nvidia-h200、nvidia-h100、nvidia-a100、nvidia-l40s、nvidia-l40、nvidia-a40、nvidia-a10、nvidia-rtx-a6000、nvidia-rtx-a5000、nvidia-rtx-a4500、nvidia-rtx-a4000、nvidia-rtx-5090、nvidia-rtx-4090、nvidia-rtx-3090	GPU 型号
card_count	整数	否	1	nvidia-b200 为 1 至 4；nvidia-h100、nvidia-h200、nvidia-a100、nvidia-l40s 为 1 至 8；其他型号均为 1 至 16	GPU 数量
duration_seconds	数字	否	600	60 至 86400	作业时长（秒）
routing_policy	字符串	否	不发送	lowest_cost、lowest_latency、zero_quota	路由策略
workload_type	字符串	否	不发送	agent_exec、fine_tune、batch_inference	工作负载类型

已发布的输入架构声明 card_count 的最大值为 16。调用时，代码会强制执行上述针对各 GPU 型号的更严格限制。

x402_run_job

为一个 GPU 作业报价并使用 Base USDC 付款。接受与 x402_quote 相同的参数，另加：

参数	类型	必填	描述
max_usd	数字	是	必须大于 0。超过此金额或任一支出上限时，将拒绝付款。
confirm	布尔值	是	必须为 true，否则不会付款。

x402_job_status

使用 x402_run_job 本地保存的 API 密钥，获取通过 x402 创建的作业状态。

参数	类型	必填	描述
job_id	字符串	是	1 至 128 个字符

get_capacity

读取当前 GPU 容量数据。只读。无需 API 密钥，也无需参数。调用 GET {KILAWATT_SITE_URL}/api/capacity。如果当前无法获取数据（HTTP 503，代码为 unavailable），工具会说明这一情况。

{ "name": "get_capacity", "arguments": {} }

get_platform_status

读取平台状态。只读。无需 API 密钥，也无需参数。调用 GET {KILAWATT_SITE_URL}/api/status。结果包含 status（operational、degraded、incident 或 unknown）、status_note、last_checked、status_page 和 latest_test_summary。

{ "name": "get_platform_status", "arguments": {} }

get_pricing

读取各 GPU 级别每 GPU 小时的参考美元价格。只读。无需 API 密钥，也无需参数。调用 GET {KILAWATT_SITE_URL}/api/pricing。这些价格仅供参考。作业的确切价格来自未付款的 x402 请求，例如 x402_quote。

{ "name": "get_pricing", "arguments": {} }

get_resume_info

检查作业能否从上一个检查点恢复。此操作为只读，不会启动任何任务或产生费用。需要 KILAWATT_API_KEY。调用 GET {KILAWATT_SITE_URL}/api/jobs/{job_id}/resume-info。

参数	类型	必填	描述
job_id	字符串	是	36 个字符，由十六进制数字和连字符组成。发送任何请求前都会进行检查。

结果包含 job_id、checkpoint_count、last_checkpoint_at、can_resume、reason（null、no_checkpoint 或 job_still_running）和 resume_action。

{ "name": "get_resume_info", "arguments": { "job_id": "YOUR_JOB_ID" } }

resume_job

启动新的付费运行，以便在不同供应商处从作业的上一个检查点恢复。**此操作会产生费用。**需要 KILAWATT_API_KEY。请先调用 get_resume_info，并在确认前询问用户。仅调用一次 POST {KILAWATT_SITE_URL}/api/jobs/{job_id}/resume，绝不会自动重试。

参数	类型	必填	描述
job_id	字符串	是	36 个字符，由十六进制数字和连字符组成
confirm	布尔值	是	必须恰好为 true
max_spend_usd	数字	是	新运行的费用上限。必须大于 0。
duration_seconds	整数	否	60 至 86400。仅在提供时发送。

所有参数都会在发送任何请求前于本地进行检查。如果检查失败，则不会发送任何内容。

{
  "name": "resume_job",
  "arguments": { "job_id": "YOUR_JOB_ID", "confirm": true, "max_spend_usd": 5 }
}

deploy_gpu_node 与 x402 工具的区别

• deploy_gpu_node 中的 gpu_type 为自由文本（最多 64 个字符），而 x402 工具中的 gpu_type 为固定列表。
• deploy_gpu_node 中的 card_count 最多允许 64，而 x402 工具中最多允许 16（部分 GPU 的上限更低）。
• deploy_gpu_node 中的 duration_seconds 允许 1 至 86400，而 x402 工具中允许 60 至 86400。
• deploy_gpu_node 默认将 routing_policy 设为 lowest_cost；除非你进行设置，否则 x402 工具不会发送路由策略。

工具结果根据 Kilawatt 网关返回的真实 HTTP 响应生成。

x402 设置

x402 工具允许你使用 Base USDC 请求算力，无需 Kilawatt 账户或 API 密钥。费用上限会在本地强制执行。

使用 x402 付款时，服务端必须能够读取以下环境变量：

变量	用途	默认值
KILAWATT_X402_PRIVATE_KEY	兼容 Base 的钱包密钥，仅用于通过 x402_run_job 付款	未设置
KILAWATT_X402_MAX_USD_PER_JOB	单个付费作业的最高费用	0.25
KILAWATT_X402_MAX_USD_PER_SESSION	此服务端进程中的累计费用上限	1.00
KILAWATT_X402_URL	覆盖 x402 执行端点	Kilawatt 生产端点

返回的 API 密钥会以受限文件权限存储在 ~/.config/kilawatt/x402-api-key。它绝不会显示在工具输出中。现有的 deploy_gpu_node 仍需要 KILAWATT_API_KEY。

**请为 x402 使用单独的小额钱包，并勿将其私钥放入提示词或共享配置中。**付款方不需要 ETH；交易由中介方提交。

对于 x402 用户：请确认你的 Base 钱包中有足够的 USDC，且费用上限允许支付相应金额。

错误处理

所有错误都会提供明确说明，并指出是否已分配资源或扣费。常见情况：

• 400 Bad Request：参数无效（例如，card_count > 64）。修正后重试。
• 401 Unauthorized：API 密钥缺失、格式错误或已撤销。请在 Kilawatt 账户中签发新密钥，或联系 [email protected]。
• 402 Payment Required：付款未获接受。请检查余额和费用上限，然后重试。
• 429 Rate Limited：达到并发或速率限制。请稍后重试。
• 503 No Capacity：没有符合条件的可用节点。请尝试其他 gpu_type 或更小的 card_count。
• Timeout：网关在 60 秒内未响应。未分配算力；如有需要，请重试。

Links

• npm Package: https://www.npmjs.com/package/kilawatt-mcp-server
• GitHub Repository: https://github.com/KilaWattCloud/kilawatt-mcp-server
• Kilawatt Cloud: https://kilawattcloud.dev
• Model Context Protocol: https://modelcontextprotocol.io

License

MIT