gammainfra

@gammainfra/mcp-server

适用于 GammaInfra 的 Model Context Protocol（MCP）服务：通过一个 OpenAI 风格的 API，在所有主流提供商之间进行智能大模型路由。

将此服务接入 Claude Code、Claude Desktop、Cursor、Cline、Continue 或任何兼容 MCP 的宿主，Agent 即可直接使用以下工具：

• chat_completions — 调用任意受支持的模型（或使用 gammainfra/auto 进行智能路由），并控制成本、延迟和质量。路由元数据（服务请求的提供商、确切的美元成本、回退链）会作为结构化的 routing_meta 字段返回。
• list_models — 完整的模型目录，包含定价和能力标志。
• get_balance — 托管余额和 BYOK 余额。
• get_status — 整体及各提供商的健康状态，以及 24 小时请求数。

快速开始

1. 获取 GammaInfra API 密钥 — 在 https://gammainfra.com/signup 免费注册（赠送 3 美元试用额度，无需信用卡）。
2. 将服务添加到 MCP 客户端配置中（下方提供各客户端的操作说明）。
3. 重启客户端。Agent 即可立即使用这四个工具。

安装

此服务通过 npx 运行，无需手动安装。首次调用时会下载并缓存软件包。

Claude Code

claude mcp add gammainfra \
  --env GAMMAINFRA_API_KEY=sk-gammainfra-... \
  -- npx -y @gammainfra/mcp-server

或者编辑 ~/.claude.json，将以下内容添加到 mcpServers 区块：

{
  "mcpServers": {
    "gammainfra": {
      "command": "npx",
      "args": ["-y", "@gammainfra/mcp-server"],
      "env": { "GAMMAINFRA_API_KEY": "sk-gammainfra-..." }
    }
  }
}

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "gammainfra": {
      "command": "npx",
      "args": ["-y", "@gammainfra/mcp-server"],
      "env": { "GAMMAINFRA_API_KEY": "sk-gammainfra-..." }
    }
  }
}

重启 Claude Desktop。“GammaInfra”服务应会出现在工具菜单中。

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "gammainfra": {
      "command": "npx",
      "args": ["-y", "@gammainfra/mcp-server"],
      "env": { "GAMMAINFRA_API_KEY": "sk-gammainfra-..." }
    }
  }
}

Cline（VS Code）

打开 Cline 设置（齿轮图标 → MCP Servers 选项卡）并添加：

{
  "gammainfra": {
    "command": "npx",
    "args": ["-y", "@gammainfra/mcp-server"],
    "env": { "GAMMAINFRA_API_KEY": "sk-gammainfra-..." },
    "disabled": false
  }
}

环境变量

变量	必需	默认值	说明
GAMMAINFRA_API_KEY	是	—	你的 GammaInfra API 密钥，格式为 sk-gammainfra-{32_chars}。
GAMMAINFRA_BASE_URL	否	https://api.gammainfra.com/v1	用于覆盖为 staging/dev 环境的地址。

工具参考

chat_completions

发送聊天补全请求，并接收模型响应和路由元数据。

参数：

名称	类型	必需	说明
model	字符串	是	使用 gammainfra/auto 进行智能路由，使用 gammainfra/fast/gammainfra/cheap 快速选择档位，或指定特定模型，例如 openai/gpt-5-mini。
messages	数组	是	OpenAI 风格的对话消息。
temperature	数字	否	0..2。
max_tokens	int	否
max_completion_tokens	int	否	GPT-5 系列要求使用此参数，而不是 max_tokens。
cost_quality	float	否	0.0..1.0 的连续调节值。作为 X-GammaInfra-Cost-Quality 发送。
max_latency_ms	int	否	60..600000。限制总墙钟时间（包括回退重试）。客户端也会强制执行此限制，超时即中止请求。
preference	字符串	否	quality、cost 或 latency。
region	字符串	否	us、eu、apac 或特定 AWS 区域。
tools、tool_choice、response_format、top_p、frequency_penalty、presence_penalty	各类	否	标准 OpenAI 字段，会原样转发。

返回值： { response: <OpenAI response>, routing_meta: { provider, endpoint, cost_usd, input_cost_usd, output_cost_usd, router_version, logical_model, fallback_chain, attempted_count, request_id, ... } }

超时说明： 每个请求都有 10 分钟的客户端硬超时（通过 AbortController 实现），避免上游请求挂起导致 MCP 进程卡住。对于 chat_completions，如果提供了 max_latency_ms，则会用它替代默认值作为硬中止时限。

流式传输说明： MCP 工具响应不采用流式传输。服务始终向上游发送 stream: false，且工具输入不接受 stream 参数（该参数会被架构验证拒绝）。如需流式传输，请直接使用 GammaInfra HTTP API。

list_models

无参数。返回完整的模型目录，包括直连指定的 slug、每个 token 的定价和功能标记（supports_tools、supports_vision）。

get_balance

名称	类型	必填	说明
include_byok	boolean	否	默认为 false。同时获取 BYOK 余额。默认关闭，以避免向未注册 BYOK 的客户发起额外请求并必然收到 404。

返回 { managed_balance_usd, byok_balance_usd, currency }。如果省略 include_byok 或将其设为 false，则 byok_balance_usd 为 null，且不会发起 BYOK 请求（不会有 byok_error）。如果设为 include_byok: true，但未注册 BYOK，则 byok_balance_usd 为 null，并会通过 byok_error 字段说明原因。

get_status

无参数。返回 GammaInfra 当前的整体运行状况、各提供商状态、实时 p50 延迟以及 24 小时请求数。

开发

git clone https://github.com/yuz0101/gammainfra-mcp-server.git
cd gammainfra-mcp-server
npm install
npm run test          # 30 tests, ~1s
npm run build         # tsc → dist/
npm run typecheck

许可证

MIT — 参见 LICENSE。