Raywake

Raywake MCP

在 Claude、ChatGPT、Cursor 和任何 MCP 客户端中使用 500 多种 AI 图像、视频和音频模型。

这是一个面向 Raywake 的开源 TypeScript MCP 服务。无需安装即可使用托管连接器 https://mcp.raywake.com/v1，也可以通过 npx 在本地使用 stdio 运行此软件包（需要 Node.js 20 或更高版本）。

获取 API 密钥

在 raywake.si/api-keys 创建密钥。为所有工具启用 models:read、generate、jobs:read 和 wallet:read。需要生成内容时，请在 raywake.si/billing 充值美元余额。浏览、报价和任务检查均免费。

请替换以下配置中的 YOUR_RAYWAKE_API_KEY。请妥善保管密钥，并避免将包含密钥的配置文件提交到版本控制系统。

Claude Code

claude mcp add raywake -e RAYWAKE_API_KEY=YOUR_RAYWAKE_API_KEY -- npx -y @raywake/mcp

Cursor

添加到 ~/.cursor/mcp.json（或项目的 .cursor/mcp.json），然后在 MCP 设置中启用 Raywake：

{
  "mcpServers": {
    "raywake": {
      "command": "npx",
      "args": ["-y", "@raywake/mcp"],
      "env": { "RAYWAKE_API_KEY": "YOUR_RAYWAKE_API_KEY" }
    }
  }
}

Claude Desktop

打开 Settings > Developer > Edit Config，并添加到 claude_desktop_config.json。保存后重启 Claude Desktop。

{
  "mcpServers": {
    "raywake": {
      "command": "npx",
      "args": ["-y", "@raywake/mcp"],
      "env": { "RAYWAKE_API_KEY": "YOUR_RAYWAKE_API_KEY" }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json，然后刷新 MCP 服务：

{
  "mcpServers": {
    "raywake": {
      "command": "npx",
      "args": ["-y", "@raywake/mcp"],
      "env": { "RAYWAKE_API_KEY": "YOUR_RAYWAKE_API_KEY" }
    }
  }
}

VS Code

添加到 .vscode/mcp.json。VS Code 会提示你输入密钥，并安全地存储该输入：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "raywake-api-key",
      "description": "Raywake API key",
      "password": true
    }
  ],
  "servers": {
    "raywake": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@raywake/mcp"],
      "env": { "RAYWAKE_API_KEY": "${input:raywake-api-key}" }
    }
  }
}

这些 JSON 示例都是完整的最简配置。将 raywake 条目合并到现有配置中，以保留其他服务。在 Windows 上，如果客户端无法启动 npx，请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "@raywake/mcp"]。

远程使用（无需安装）

Raywake 也通过 Streamable HTTP 托管相同的工具：

https://mcp.raywake.com/v1

• Claude.ai / Claude Desktop： Settings > Connectors > Add custom connector，粘贴 URL，然后使用 Raywake 账户登录。
• ChatGPT： Settings > Connectors > Create（开发者模式），粘贴 URL，然后使用 Raywake 账户登录。
• Claude Code： 运行 claude mcp add --transport http raywake https://mcp.raywake.com/v1，然后运行 /mcp 登录。若要改用 API 密钥，请添加 --header "Authorization: Bearer YOUR_RAYWAKE_API_KEY"。

OAuth 连接会在登录时设置每次生成的支出上限，并在 30 天后过期；你可以随时在 Raywake 设置中断开连接。

工具

工具	费用	用途
search_models	免费	按 query、category、modality（image、video、audio）和 page 搜索（从 1 开始；每页 20 条结果）
list_categories	免费	列出可用类别
get_model	免费	查看准确的输入架构和参考起始价格（美元）
quote	免费	为准确的 model 和 input 定价；返回 quote_id、price_usd、expires_at
generate	付费	提交已批准的准确 model、input、quote_id；可选 idempotency_key，用于恢复操作
get_job	免费	查看 job_id、输出和状态；可选 wait_seconds，范围为 0 到 45
list_jobs	免费	列出账户历史记录；可选 limit（1–500）、offset、status
get_account	免费	查看美元余额，包括可用、预留和欠款
get_playbook	免费	查看简要工作流和支出规则

search_models 会将 query 映射到 API 的 search，并将 page 映射到 limit / offset。由于 API 没有模态参数，因此会在本地根据类别和标签匹配模态，再进行分页。部分模型可能匹配多个模态。get_model 会保留网关的 openapi 架构，并在必要时根据零售价格指南推导起始价格。起始价格按返回的单位计价，例如每张图像或每秒；它并非完整运行的报价。若无法获取起始价格，则返回 null。

示例提示词

• “查找适用于产品摄影的图像模型，并比较其以 USD 计价的起步价格。”
• “显示此模型的架构，为我准备输入并获取报价。消费任何费用前先询问我。”
• “使用此公开 HTTPS 图像 URL 为一段短视频报价。生成前向我显示价格。”
• “我批准此报价价格和输入。生成内容，然后检查现有任务，直到完成。”
• “显示我最近的任务并获取最新结果。”
• “我有多少可用的 USD 余额？”

哪些操作会产生费用

只有 generate 会消耗你的 Raywake 余额。搜索、查看架构、获取报价、读取钱包和轮询任务均免费。助手必须遵循以下步骤：

1. 搜索模型并使用 get_model 读取其架构。
2. 使用完整输入调用 quote。
3. 向你显示 USD 价格、有效期，以及这是否为基于用量的最高预留金额，并征求你的批准。
4. 使用完全相同的模型、输入和报价 ID 调用 generate。
5. 继续使用 get_job；轮询不会启动另一次生成。

报价中的 settles_on_usage 标志表示最高预留金额：按实际计费的用量收费，未使用的余额会退回。若报价已过期或输入已更改，请获取新报价并重新征求批准。如果余额不足，请充值。

批准是一项通过描述和内置操作手册传达给助手的规则；服务无法独立验证对话中是否获得了人工批准。你的 MCP 客户端确认设置应要求对付费的 generate 工具进行批准。报价所有权、有效期和精确输入绑定由 Raywake 的网关强制执行；此外，对于此进程已知的报价，还会进行额外的匹配检查。

等待和安全重试

generate 最多等待 45 秒（包括提交时间），然后返回已知的 job_id、最新状态和生成的 idempotency_key。如果轮询失败，它会保留任务引用。请继续使用 get_job，并将 wait_seconds 设为最多 45。终止状态包括 succeeded、failed、needs_review、submission_unknown 和 needs_reconciliation。审核和对账状态需要处理；不要自动提交替代任务。

请保存 idempotency_key，包括错误结果中的密钥。如果提交响应丢失，请使用相同的密钥、模型、输入和报价 ID 重试 generate。对于完全相同的重试请求，网关会返回现有任务，即使报价已过期也是如此。切勿使用新密钥来恢复状态不确定的提交。在运行中的服务内，重复相同的生成请求也会复用已保存的密钥。重启后，请提供已保存的密钥；对于本地内存中已不存在的报价，网关仍是恢复操作的权威来源。密钥和报价指纹仅保存在内存中。如果整个工具响应和进程都丢失，请使用 list_jobs 查找现有任务，再进行任何可能再次产生费用的操作。

媒体输入

没有上传工具：API 密钥无法上传媒体资源。接受图像、视频或音频 URL 的模型，需要在 get_model 指定的字段中提供可公开访问的 HTTPS URL。请先将本地文件托管到公开位置。不能将本地路径、file://、私有 URL 和 data: URL 用作上传媒体。输出链接可能是临时链接；请再次调用 get_job 以获取当前链接。

配置

环境变量	必填	默认值
RAYWAKE_API_KEY	是	无；作为 Bearer 令牌发送
RAYWAKE_API_BASE	否	https://api.raywake.com

基础 URL 覆盖值必须使用 HTTPS；仅在本地模拟环境中允许使用 localhost 上的 HTTP。该值不得包含凭据、查询参数或片段。只使用你信任的覆盖值：它会接收你的 API 密钥。重定向会被拒绝。服务将标准输出保留给 MCP 使用，且绝不会记录密钥或上游原始错误正文。

隐私

为完成你的请求，提示词和输入会发送给 Raywake 和所选的模型提供商。你的 MCP 客户端也会处理对话和工具结果。请勿在模型输入中包含机密信息。此本地软件包不会添加分析功能，也不会将提示词、密钥、报价或结果写入磁盘。客户端日志记录和各项服务的数据保留政策另行适用。

开发

npm install
npm run build
npm test
npm run smoke

npm test 会构建 CLI，使用 Vitest 配合模拟的 fetch 和虚拟凭据，并在不访问 API 的情况下检查真实的 stdio 工具发现。单独的 npm run smoke SDK 测试会在 127.0.0.1 上启动自己的 HTTP 服务并使用虚拟密钥，启动编译后的 CLI，列出全部九个工具，并测试发现、报价、生成和作业检索。这两个命令都不会调用 api.raywake.com。HTTP 冒烟测试需要获准绑定本地端口；受限沙盒可能会以 EPERM 拒绝该操作。

若要将 MCP 客户端连接到此未发布的检出版本，请将 npx 配置替换为 "command": "node" 和 "args": ["/absolute/path/to/raywake-mcp/dist/index.js"]；环境配置保持不变。构建后，可通过终端启动：

RAYWAKE_API_KEY=YOUR_RAYWAKE_API_KEY node dist/index.js

server.json 是发布到官方 MCP 注册表的元数据，名称为 si.raywake/mcp。发布版本和发布到注册表是两个独立的手动步骤。npm 软件包的 mcpName 与 si.raywake/mcp 一致；版本字段必须保持同步。

这种精简的 TypeScript/npm/stdio 结构受到 Wiro-MCP（MIT）的启发。Raywake 使用自己的 Bearer 身份验证、先报价再生成的工作流和网关契约。没有复制 Wiro 的源代码。

许可证

MIT，版权归 Raywake 所有。