Skip to content
项目

runapi-ai/mcp has 56 GitHub stars and 0 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 18:25 UTC. Last push 2026-11-03.

这些数字如何统计

实测星标增长

24小时
0
7天
更新延迟
15天
更新延迟
1个月
更新延迟

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

RunAPI MCP server for model discovery, pricing lookup, media task creation, and balance checks.

创作与媒体

README.zh-CN.md

原文

RunAPI MCP Server

一个 MCP Server,把 160+ 个可执行模型、4 种模态的模型发现、价格查询、媒体任务和账户状态接入 AI 编程工具。

npm version Apache-2.0 license MCP Server


这是什么?

RunAPI MCP Server 让 Claude Code、Cursor、VS Code、Windsurf、Roo 等 MCP Host 可以直接使用 RunAPI。 它支持浏览模型目录、查看模型输入参数、查询价格快照、创建媒体任务、轮询任务状态和查询账户余额。

目录发现工具不需要 API Key,因为它们使用包内嵌的构建时目录数据。 认证工具可以使用 login tool、runapi login、RUNAPI_API_KEY 或共享的 RunAPI config。


Hosted MCP

远程 MCP Client 可以直接连接:

https://mcp.runapi.ai/mcp

无需安装 Node.js。Client 支持远程 MCP 授权时使用 OAuth,也可以把 RunAPI API Key 配置为 bearer credential。Cursor、Claude Desktop、VS Code 和 Windsurf 的配置见 Hosted MCP 设置页面。

Hosted MCP 提供下文列出的 8 个 Business Tools。Local Login 只保留在 Local MCP package 中。


快速开始

通过 stdio 使用 Local MCP 时,推荐使用 Claude Code 的 MCP 命令安装:

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

scope 参数决定 MCP Server 配置保存在哪里:

  • -s user:全局配置,对当前用户的所有项目可用。
  • -s project:团队共享配置,写入当前仓库的 .mcp.json,可以提交到 repo。

如果希望团队共享同一份配置,使用 project scope:

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

非 Claude Code 平台或手动 JSON 配置的兼容 fallback:

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

如果你的 MCP Host 需要生成平台专用配置文件,可以把旧的 init 命令作为 fallback:

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 tool。它会打开浏览器登录,并把凭据保存到 ~/.config/runapi/config.json,也就是 runapi login 使用的同一个文件。 无浏览器或 CI 环境仍然可以在启动 MCP Host 前设置 RUNAPI_API_KEY。


工具

Tool 认证 用途
list_models 否 从内嵌目录列出 RunAPI 模型,支持 modality、service、action 过滤。
get_model_info 否 返回某个模型 slug 的 service、action、modality、输入约束和价格快照。模型出现在多个 endpoint 时,带上 service + action 精确查询。
list_actions 否 按 modality 分组列出 endpoint action 名称。
check_pricing 否 查询 service + action + model 组合的价格快照。
search_prompts 否 按 modality、category、tags、q、model、featured 和分页搜索可复用 prompt 示例。每条 prompt 返回 media:审核通过的示例图片(包括视频 prompt 的封面图)。示例视频和参考图暂不返回。
login 否 打开浏览器登录,并把 RunAPI 凭据保存到共享本地配置。
create_task 是 使用调用方生成的必填 idempotency_key 创建媒体任务;默认等待完成,也可用 wait: false 立即返回。
get_task 是 查询已有媒体任务的状态和最新 payload。
check_balance 是 查询账户余额和消费指标。

示例

你可以用自然语言让助手调用工具。 助手应该通过工具发现当前模型 slug 和价格,而不是依赖记忆里的模型名。

浏览目录

RunAPI 有哪些图片模型?

预期行为:

  1. 调用 list_models,传入 modality: "image"。
  2. 总结返回的 model slug、service、action 和 required fields。
  3. 除非调用 check_pricing,否则不直接报价。

搜索 Prompt 示例

找一些 logo 图片 prompt 示例。

预期行为:

  1. 调用 search_prompts,传入 modality: "image" 和 q: "logo"。
  2. 总结返回的 title、prompt text、model slug、category、tags 和示例图片地址。
  3. 创建任务前,先用 get_model_info 检查选中模型的参数约束。

查看模型参数

查看这个模型 slug 的必填参数:<model-slug>

预期行为:

  1. 调用 get_model_info。
  2. 如果返回 ambiguous,从 matches 里选择相关 service/action,并带上 service 和 action 再调用一次 get_model_info。
  3. 展示 required fields、enum、range、条件输入规则、支持的 action 和价格快照。
  4. 如果 slug 不存在,提示先用 list_models 选择有效 slug。

创建媒体任务

用 RunAPI 生成一张方形产品图,帮我选合适的图片模型。

预期行为:

  1. 调用 list_models 选择兼容的图片模型。
  2. 带上选定的 service/action/model 调用 get_model_info 验证参数和条件输入规则。
  3. 如果请求昂贵、耗时或批量,先确认。
  4. 为这个逻辑任务生成一个 opaque idempotency_key,再调用 create_task。
  5. 返回 task ID、status、output URLs 和可用的 cost 字段。

等待任务完成

Hosted MCP 对异步 create_task(wait: true) 使用 request-scoped SSE,最长等待 300 秒。它约每 5 秒轮询一次、约每 15 秒发送一次 SSE heartbeat;只有 MCP 客户端提供 progressToken 时才发送标准 notifications/progress。terminal JSON-RPC response 会在同一 stream 中返回,随后关闭 stream。

terminal tool result 的 structuredContent 与 text content 语义一致,包含 task_id、最终 status、completed: true 和 RunAPI result。参数示例见 examples/create-task-and-wait.arguments.json。

只提交不等待

创建任务,但不要等待完成。

预期行为:

  1. 生成一个 opaque idempotency_key,再调用 create_task 并传入 wait: false。
  2. 返回 task ID。
  3. 之后可以用 get_task 查询状态。

安全重放任务创建

create_task 要求 1 到 512 个字符的 opaque idempotency_key。每个逻辑任务生成一个新 key,并把它与该任务的 service、action、model 和 params 一起保留。

如果连接中断或超时导致创建结果未知,不要自动创建另一个任务。只有在确实需要重试时,才对相同输入复用原 key;对不同输入复用同一个 key 会返回 conflict。不要从 JSON-RPC request ID 或 X-Client-Request-Id 推导这个 key。

Completion Wait 达到 deadline 时,task 创建仍然成功。这个非错误结果会在 structured 与 text content 中一致返回 task_id、最新 status、completed: false、wait_deadline_reached: true 和 next_action: "get_task"。继续使用 get_task 查询,不要创建替代 task。

如果 task 创建后 polling 失败或连接中断,task 仍可能继续处理。继续使用 get_task 查询,不要创建替代 task。

只提交不等待的参数结构见 examples/create-task.arguments.json。

查询余额

查询我的 RunAPI 余额。

预期行为:

  1. 调用 check_balance。
  2. 如果没有配置 key,调用 login 进行浏览器登录;无浏览器环境则说明如何设置 RUNAPI_API_KEY。

Catalog Coverage

MCP Embedded Catalog 来自 RunAPI 的 contract 快照。 它只包含当前 server 版本可执行的模型,共 160+ 个模型、4 种模态。

Modality 使用方式
Image list_models with modality: "image"
Video list_models with modality: "video"
Audio and music list_models with modality: "audio"
Utility list_models with modality: "utility"

目录内容会随着版本变化。 请用 list_models 获取当前 service/action/model slugs,用 get_model_info 查看当前约束。


Pricing

MiniMax H3 价格

价格通过 check_pricing 工具和公开 pricing 页面查询。 不要依赖 README 示例里的固定数字。

推荐流程:

  1. 调用 list_models 找候选模型。
  2. 调用 check_pricing,传入 service、action 和 model。
  3. 展示返回的价格快照,或链接到 runapi.ai/pricing。

免费目录工具不会创建任务,也不会消耗余额。


平台配置

Claude Code、Cursor、Windsurf 和 VS Code

运行:

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

-s user 表示全局安装,对所有项目可用。 -s project 表示让 Claude Code 在仓库里写入 .mcp.json,用于团队共享配置。

修改 MCP 配置后,重启或重新加载你的 MCP Host。

兼容 Fallback:生成配置文件

只有当 Host 需要平台专用 JSON 文件,或无法使用 Claude Code MCP 命令时,才使用 init。

Claude Code fallback:

npx @runapi.ai/mcp init claude

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

Cursor fallback:

npx @runapi.ai/mcp init cursor

会写入 .cursor/mcp.json。

VS Code fallback:

npx @runapi.ai/mcp init vscode

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

Windsurf fallback:

npx @runapi.ai/mcp init windsurf

Roo Code

npx @runapi.ai/mcp init roo

会写入 .roo/mcp.json。


配置

Server 按以下顺序读取配置:

  1. RUNAPI_API_KEY 环境变量,适合无浏览器和 CI 环境
  2. ~/.config/runapi/config.json,由 MCP login tool 或 runapi login 创建
  3. 无 key,仅允许免费目录工具

配置文件通常由登录流程管理。无浏览器环境预置配置时可以使用:

{
  "apiKey": "your_runapi_key"
}

不要提交真实 API Key。


Data Sync

包内包含构建时数据:

  • data/contract.json:目录、action、model slug 和输入约束

发布前刷新 contract 数据:

npm run sync:data

开发

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

本地启动:

npm run dev

Package Contents

npm 包包含:

  • 编译后的 dist/
  • 内嵌 data/
  • 平台示例
  • eval scenarios
  • README、CHANGELOG、LICENSE、package metadata

不包含 node_modules、.env、本地配置文件或 API Key。


License

Licensed under the Apache License, Version 2.0.