Runapi Mcp Server

RunAPI MCP 服务

AI 图像生成、视频生成、音乐创作、文本转语音、提示词搜索和模型发现——一个 MCP 服务涵盖 4 种模态的 160 多个可执行模型。

_{适用于 Claude Code、Codex、Cursor、Windsurf、VS Code、Roo Code，以及任何兼容 MCP 的宿主。}

快速开始 | 工具 | 示例 | 目录 | 平台

---

这是什么？

RunAPI MCP 服务将兼容 MCP 的编码工具连接到 RunAPI。 它让助手可以浏览 RunAPI 目录、查看模型输入、查询当前运行价格、创建媒体任务、轮询任务状态，以及查看账户余额。

发现类工具使用内嵌的构建时目录，无需 API 密钥即可使用。 需要身份验证的操作可通过 login 工具、runapi login、RUNAPI_API_KEY 或共享的 RunAPI 配置进行。

此软件包是纯客户端。 它不运行本地生成后端，只有需要身份验证的工具才需要登录 RunAPI。

---

托管 MCP

远程 MCP 客户端可以直接连接到：

https://mcp.runapi.ai/mcp

无需安装 Node.js。客户端支持远程 MCP 授权时，请使用 OAuth；也可以将 RunAPI API 密钥配置为 bearer 凭证。Cursor、Claude Desktop、VS Code 和 Windsurf 的配置请参阅托管 MCP 设置页面。

托管 MCP 提供下文介绍的 8 个业务工具。本地登录仅在本地 MCP 软件包中提供。

---

快速开始

对于通过 stdio 运行的本地 MCP，请使用 Claude Code 的 MCP 命令安装 RunAPI：

claude mcp add runapi -s user -- npx -y @runapi.ai/mcp

作用域标志用于控制 MCP 服务的存储位置：

• -s user：全局设置，对你的所有项目均可用。
• -s project：团队共享，写入当前仓库的 .mcp.json，因此可以提交到版本库。

希望整个团队共享同一服务配置时，请使用项目作用域：

claude mcp add runapi -s project -- npx -y @runapi.ai/mcp

非 Claude Code 平台或手动配置 JSON 时，可使用此兼容性备用方案：

{
  "mcpServers": {
    "runapi": {
      "command": "npx",
      "args": ["-y", "@runapi.ai/mcp"]
    }
  }
}

如果宿主需要生成配置文件，可使用旧版 init 命令作为备用方案：

npx @runapi.ai/mcp init claude
npx @runapi.ai/mcp init cursor
npx @runapi.ai/mcp init vscode
npx @runapi.ai/mcp init windsurf
npx @runapi.ai/mcp init roo

无需登录即可使用免费目录工具。 如需创建任务、查询任务状态和查看余额，请让助手调用 login 工具。此工具会打开浏览器登录，并将凭证保存到 ~/.config/runapi/config.json，与 runapi login 使用同一文件。 无头环境和 CI 宿主也可以在启动 MCP 宿主之前设置 RUNAPI_API_KEY。

---

工具

工具	身份验证	用途
list_models	否	列出内置目录中的 RunAPI 模型。支持按 modality、service 和 action 筛选。
get_model_info	否	返回指定模型 slug 的服务、操作、模态、输入限制和当前运行时定价。如果某个模型出现在多个端点中，请使用 service + action。
list_actions	否	按模态对端点操作名称进行分组。
check_pricing	否	返回指定 service + action + model 组合的当前运行时定价。
search_prompts	否	按 modality、category、tags、q、model、featured 和分页参数搜索可复用的提示词示例。
login	否	启动浏览器登录，并将 RunAPI 凭据保存到共享本地配置中。
create_task	是	使用调用方生成的必需 idempotency_key 创建媒体任务；默认等待任务完成，也可通过 wait: false 立即返回。
get_task	是	获取现有媒体任务的状态和最新负载。
check_balance	是	返回账户余额和支出指标。

目录、定价和提示词搜索工具专为编码工具中的漏斗顶部发现而设计。 任务和余额工具专为经过身份验证的工作流而设计。

---

示例

用自然语言向你的助手提问。 助手应使用工具查询当前模型 slug 和定价，而不是依赖记忆中的名称。

浏览目录

What RunAPI image models are available?

预期行为：

1. 助手使用 modality: "image" 调用 list_models。
2. 助手总结返回的模型 slug、服务、操作和必填字段。
3. 除非调用 check_pricing，否则不引用过时的价格。

搜索提示词示例

Find image prompt examples for a logo.

预期行为：

1. 助手使用 modality: "image" 和 q: "logo" 调用 search_prompts。
2. 助手总结返回的标题、提示词文本、模型 slug、类别和标签。
3. 助手在创建任务之前，使用选定的提示词调用 get_model_info。

查看模型信息

Show me the required parameters for this model slug: <model-slug>

预期行为：

1. 助手调用 get_model_info。
2. 如果响应含糊不清，助手从返回的匹配项中选择相关的服务/操作，并再次使用 service 和 action 调用 get_model_info。
3. 助手展示必填字段、枚举约束、范围约束、条件输入规则、支持的操作，以及可用时的当前运行时定价。
4. 如果未找到该 slug，助手会提示你使用 list_models 选择另一个 slug。

创建媒体任务

Generate a square product image with RunAPI. Pick a suitable image model.

预期行为：

1. 助手调用 list_models，选择兼容的图像模型。
2. 助手使用选定的服务/操作/模型调用 get_model_info，以查看参数说明。
3. 如果请求成本较高、运行时间较长或属于批量任务，助手会请求确认。
4. 助手为此逻辑任务生成一个不透明的 idempotency_key，并调用 create_task。
5. 在可用时，助手返回任务 ID、状态、输出 URL 和成本字段。

等待完成

托管式 MCP 会将带有 wait: true 的异步 create_task 调用保持为请求范围内的 SSE，最长 300 秒。它大约每 5 秒轮询一次，每 15 秒左右发送一次 SSE 心跳；只有在 MCP 客户端提供了 progressToken 时，才会发送标准的 notifications/progress。最终的 JSON-RPC 响应会在同一数据流中到达，随后数据流关闭。

最终工具结果包含匹配的 structuredContent 和文本内容，其中包括 task_id、最终 status、completed: true 以及 RunAPI result。请参阅 examples/create-task-and-wait.arguments.json。

提交后不等待

Create the task but do not wait for completion.

预期行为：

1. 助手生成一个不透明的 idempotency_key，并使用 wait: false 调用 create_task。
2. 助手返回任务 ID。
3. 之后你可以使用 get_task 查询状态。

安全地重试任务创建

create_task 要求提供一个长度为 1 到 512 个字符的不透明 idempotency_key。每个逻辑任务都生成一个新密钥，并将其与该任务使用的确切 service、action、model 和 params 一并保存。

如果连接关闭或超时，导致创建结果未知，请勿自动创建另一个任务。只有在确有需要时才重试，并使用相同密钥和相同输入。使用不同输入复用该密钥会返回冲突。请勿根据 JSON-RPC 请求 ID 或 X-Client-Request-Id 生成密钥。

当 Completion Wait 达到截止时间时，任务创建仍然成功。非错误结果的结构化内容和文本内容一致，其中包含 task_id、最新的 status、completed: false、wait_deadline_reached: true 和 next_action: "get_task"。继续调用 get_task；请勿创建替代任务。

如果在任务创建后轮询失败或连接关闭，任务仍可能正在处理中。继续调用 get_task；请勿创建替代任务。

提交专用参数请参见 examples/create-task.arguments.json。

检查账户余额

Check my RunAPI balance.

预期行为：

1. 助手调用 check_balance。
2. 如果未配置密钥，则调用 login 进行浏览器登录，或说明无头主机需要配置 RUNAPI_API_KEY。

目录覆盖范围

MCP Embedded Catalog 根据 RunAPI 的契约快照生成。 其中仅包含此服务版本可执行的模型。

模态	使用方法
图像	使用 list_models，并设置 modality: "image"
视频	使用 list_models，并设置 modality: "video"
音频和音乐	使用 list_models，并设置 modality: "audio"
实用工具	使用 list_models，并设置 modality: "utility"

目录内容可能随版本发布而变化。 使用 list_models 获取当前的服务、操作和模型标识，使用 get_model_info 获取每个模型当前的限制条件。

---

定价

MiniMax H3 定价

RunAPI 定价通过 check_pricing 工具和公开定价页面提供。 请勿依赖 README 文件中的示例获取准确价格。

常用流程：

1. 调用 list_models 查找候选模型。
2. 使用 service、action 和 model 调用 check_pricing。
3. 显示返回的当前价格，或提供 runapi.ai/pricing 链接。

免费的目录工具不会创建任务，也不会消耗账户余额。

---

平台设置

Claude Code、Cursor、Windsurf 和 VS Code

运行：

claude mcp add runapi -s user -- npx -y @runapi.ai/mcp

使用 -s user 进行全局安装，使其在所有项目中可用。 如果希望 Claude Code 在仓库中写入 .mcp.json，以便团队共享配置，请使用 -s project。

更改 MCP 配置后，请重启或重新加载 MCP 主机。

兼容性备用方案：生成配置

只有在主机需要特定平台的 JSON 文件，或无法使用 Claude Code MCP 命令时，才使用 init。

Claude Code 备用方案：

npx @runapi.ai/mcp init claude

这会在当前目录中写入 .mcp.json。

Cursor 备用方案：

npx @runapi.ai/mcp init cursor

这会写入 .cursor/mcp.json。 打开 Cursor 设置，确认 MCP 服务已启用。

VS Code 备用方案：

npx @runapi.ai/mcp init vscode

这会写入 .vscode/mcp.json。 VS Code 生成的配置使用顶层 servers 键和 type: "stdio"。

Windsurf 备用方案：

npx @runapi.ai/mcp init windsurf

这会为 init 命令指定的 Windsurf 目标写入生成的配置。

Roo Code

运行：

npx @runapi.ai/mcp init roo

这会写入 .roo/mcp.json。

手动配置

使用 examples/ 中的示例文件作为起点。 各平台的包装键和文件路径略有不同，但运行的命令都相同：

npx -y @runapi.ai/mcp

---

配置

服务按以下顺序读取配置：

1. RUNAPI_API_KEY 环境变量，适用于无头环境和 CI 主机
2. ~/.config/runapi/config.json，由 MCP login 工具或 runapi login 创建
3. 不设置密钥，此时仍可使用免费目录工具

配置文件通常由 login 管理。预置的无头配置可以使用：

{
  "apiKey": "your_runapi_key"
}

你也可以设置自定义基础 URL，用于本地测试：

{
  "apiKey": "your_runapi_key",
  "baseUrl": "https://runapi.ai"
}

请勿提交真实 API 密钥。

---

数据同步

此软件包包含构建时的合约数据：

• data/contract.json：目录、操作、模型 slug 和输入约束

发布新版本前，请从 RunAPI 源代码树刷新数据：

npm run sync:data

合约更新需要发布新版本的软件包。定价通过 RunAPI 运行时 API 查询，不使用软件包快照。

---

开发

npm install
npm run typecheck
npm test
npm pack --dry-run

在本地运行服务：

npm run dev

手动初始化冒烟测试：

printf '%s\n' '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}},"id":1}' | npx tsx src/index.ts

---

软件包内容

npm 软件包包含：

• 编译后的 dist/ 文件
• 内嵌的 data/ 文件
• 平台示例
• 由此仓库生成的评测场景
• README、变更日志、许可证和软件包元数据

其中不包含 node_modules、.env、本地配置文件或 API 密钥。

---

也可通过 CLI 使用

RunAPI 还提供了一个独立的命令行客户端，用于终端工作流。 如果你希望在 MCP 宿主中使用 RunAPI，请使用此 MCP 服务。 如果你需要直接执行 shell 命令、脚本或集成 CI，请使用 CLI。

---

许可证

根据 Apache License, Version 2.0 授权。