three.ws Brain

@three-ws/brain-mcp

任意模型，一个接口 — 从任何 AI Agent 发现大模型提供商，并通过 three.ws 多提供商路由器运行聊天补全。

---

一个通过 stdio 为任何 AI 助手提供 three.ws 多提供商大模型路由器的 Model Context Protocol 服务。探索可用模型 — Claude、GPT-5.6 系列、o3、Grok、Qwen、DeepSeek、NVIDIA Nemotron、IBM Granite 等 — 并选择合适的模型运行聊天补全，无需自行接入各家厂商的 SDK。

该路由器通过单一端点连接所有提供商；如果所选模型暂时不可用，它会在镜像和免费套餐间自动回退。免费开放权重套餐（GPT-OSS 120B、NVIDIA NIM 模型）无需密钥即可使用；付费官方旗舰模型则需要 three.ws API 密钥。

安装

npm install @three-ws/brain-mcp

也可以通过 npx 运行（无需安装）：

npx @three-ws/brain-mcp

快速开始

Claude Code，一行命令：

claude mcp add brain -- npx -y @three-ws/brain-mcp

若要启用付费旗舰模型，请传入 three.ws API 密钥：

claude mcp add brain -e THREE_WS_API_KEY=sk_live_… -- npx -y @three-ws/brain-mcp

Claude Desktop / Cursor（claude_desktop_config.json 或 mcp.json）：

{
	"mcpServers": {
		"brain": {
			"command": "npx",
			"args": ["-y", "@three-ws/brain-mcp"],
			"env": { "THREE_WS_API_KEY": "sk_live_…" }
		}
	}
}

使用 MCP Inspector 检查可用功能：

npx -y @modelcontextprotocol/inspector npx @three-ws/brain-mcp

工具

工具	类型	功能
list_providers	只读	列出路由器可访问的所有大模型 — 密钥、网络、套餐、最大输出长度、实时可用性，以及是否需要身份验证。
chat	只读	通过所选提供商运行聊天补全；返回完整回复、所用路由、令牌用量和耗时。

这两个工具都会读取实时数据 — 提供商列表和补全结果会随调用而变化，因此都不是幂等的。chat 不会更改任何平台状态，因此标注为只读。

输入参数

list_providers — 无参数。

chat — messages（必填：1–100 轮 { role: "user" | "assistant", content } 对话，content ≤ 16,000 个字符）、provider（来自 list_providers 的提供商密钥，默认为 gpt-oss-120b）、system（可选的系统提示词，≤ 8,000 个字符）、maxTokens（可选，64–16384，默认值为 4096，并限制在模型上限以内）。

示例

以下两个响应仅用于展示数据结构 — 实际提供商列表和生成结果会有所不同。

// list_providers (example response)
> {}
{
  "ok": true,
  "count": 34,
  "available": 33,
  "default_provider": "gpt-oss-120b",
  "providers": [
    { "key": "gpt-oss-120b", "label": "GPT-OSS 120B", "network": "OpenAI · OpenRouter", "tier": "balanced", "maxOutput": 8192, "description": "Open-weight 120B from OpenAI. Fast, capable, free tier. Platform default.", "available": true, "requiresAuth": false },
    { "key": "claude-sonnet-5", "label": "Claude Sonnet 5", "network": "Anthropic", "tier": "balanced", "maxOutput": 16384, "description": "Near-Opus quality on coding and agentic work at Sonnet cost. Best for most tasks.", "available": true, "requiresAuth": true },
    { "key": "deepseek-r1", "label": "DeepSeek R1", "network": "DeepSeek", "tier": "reasoning", "maxOutput": 8192, "description": "Open reasoning model. Strong at math and code.", "available": true, "requiresAuth": true }
    /* … */
  ]
}

// chat (example response)
> {
    "provider": "claude-sonnet-5",
    "system": "You are terse.",
    "messages": [{ "role": "user", "content": "Name three Solana RPC methods." }]
  }
{
  "ok": true,
  "provider": "claude-sonnet-5",
  "model": "Claude Sonnet 5",
  "network": "Anthropic",
  "tier": "balanced",
  "routed_via": null,
  "content": "getBalance, getAccountInfo, getSignaturesForAddress.",
  "usage": { "input_tokens": 24, "output_tokens": 14, "total_tokens": 38 },
  "timing_ms": { "first_token": 412, "total": 980 }
}

当请求的提供商直接响应时，routed_via 为 null；否则，它会标明路由器回退到的镜像或免费套餐路由（因此，即使首选模型暂时不可用，你也总能得到回答）。

模型可用性是动态变化的。请始终先调用 list_providers，不要将密钥硬编码。目前的 Claude ID 为 claude-fable-5、claude-opus-5、claude-sonnet-5、claude-opus-4-7、claude-sonnet-4-6 和 claude-haiku-4-5，但实时列表才是准确信息来源。

身份验证

模型类别	需要密钥？
免费开放权重层级（GPT-OSS 120B，以及 NVIDIA NIM 系列：Nemotron 3 Super / Nemotron Super 49B / Nemotron Nano / DeepSeek V4 / Kimi K2 / Llama 4 Maverick / MiniMax M2）	否
付费一方旗舰模型（Claude、GPT-5.6、o3、Qwen Plus、DeepSeek 等）	是 — 设置 THREE_WS_API_KEY

在 three.ws/dashboard/developers 创建 API 密钥。没有密钥时，付费模型会返回登录错误，list_providers 会将它们标记为 requiresAuth: true。

要求

• Node.js >= 20。
• 可访问网络 https://three.ws（或你自己的 THREE_WS_BASE）。

环境变量

变量	必需	默认值	用途
THREE_WS_BASE	否	https://three.ws	API 基础 URL（可覆盖以使用自托管服务或指定预览环境）。
THREE_WS_API_KEY	否	—	解锁付费一方旗舰模型的 Bearer 凭据。
THREE_WS_TIMEOUT_MS	否	120000	单次请求超时时间（补全内容由服务端流式传输）。

错误

工具调用失败时会返回 MCP 错误结果（isError: true），其文本为单个 JSON 对象 — { "ok": false, "error": "<code>", "message": "…" }；上游拒绝请求时还会附带 status 和 detail：

error	含义	恢复方法
upstream_error	路由器拒绝了请求 — status 携带实际 HTTP 状态码：400（参数错误或未知的提供商密钥）、401（付费模型未提供有效的 THREE_WS_API_KEY）、429（请求受速率限制）、502（模型流在生成输出前失败）。	根据 status 采取措施；对于 401，设置密钥；对于未知密钥，重新运行 list_providers。
timeout	在 THREE_WS_TIMEOUT_MS 时间内未收到完整响应。旗舰模型生成内容可能较慢 — 默认的 120 s 与路由器自身的上限一致。	重试、降低 maxTokens，或选择 fast 层级的提供商。
network_error	请求未能到达路由器（DNS、离线或 TLS 问题）。	检查网络连接 / THREE_WS_BASE。
bad_config	THREE_WS_TIMEOUT_MS 不是正数（启动时抛出）。	修正环境变量。

如果请求的提供商在处理中途失败，路由器会透明地切换到镜像或免费层级，回复中的 routed_via 会标明采用的路由 — 只有所有路由都耗尽时才会看到错误。

链接

• 主页：https://three.ws
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，参见 LICENSE

---

_{属于 three.ws SDK 套件 — 3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}