内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/brain-mcp</h1>
<p align="center"><strong>任意模型，一致接口 — 通过 three.ws 多供应商路由器发现 LLM 提供商并运行聊天补全功能，适用于任何 AI 代理。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/brain-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/brain-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/brain-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/brain-mcp?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-0ea5e9"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为任何 AI 助手提供 three.ws **多供应商 LLM 路由器**，通过标准输入输出。发现可用的模型 — Claude, GPT-4o, o3, Qwen, DeepSeek, NVIDIA Nemotron, IBM Granite 等 — 并通过最合适的模型运行聊天补全，无需为每个供应商的 SDK 进行单独配置。
路由器在单个端点后面隐藏所有提供商，并在所选模型暂时不可用时透明地回退到镜像和免费层级。免费的开放权重层级（GPT-OSS 120B，NVIDIA NIM 模型）无需密钥即可使用；付费的第一方旗舰模型需要 three.ws API 密钥。
## 安装
```bash
npm install @three-ws/brain-mcp
```
或使用 `npx`（无需安装）：
```bash
npx @three-ws/brain-mcp
```
## 快速开始
**Claude Code**，一行命令：
```bash
claude mcp add brain -- npx -y @three-ws/brain-mcp
```
要解锁付费旗舰模型，请传递您的 three.ws API 密钥：
```bash
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`）：
```json
{
"mcpServers": {
"brain": {
"command": "npx",
"args": ["-y", "@three-ws/brain-mcp"],
"env": { "THREE_WS_API_KEY": "sk_live_…" }
}
}
}
```
使用 MCP 检查器检查表面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/brain-mcp
```
## 工具
| 工具 | 类型 | 功能 |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
| `list_providers` | 只读 | 列出路由器可以访问的所有 LLM — 密钥、网络、层级、最大输出、实时可用性和是否需要身份验证。 |
| `chat` | 只读 | 通过选择的提供商运行聊天补全；返回完整的回复、路由、 token 使用情况和时间。 |
这两个工具都读取实时数据 — 提供商集和补全结果在每次调用之间可能会有所不同，因此两者都不是幂等的。`chat` 不会修改任何平台状态，因此被注释为只读。
### 输入参数
**`list_providers`** — 无参数。
**`chat`** — `messages`（必需：`{ role: "user" | "assistant", content }` 数组），`provider`（来自 `list_providers` 的提供商密钥，默认为 `gpt-oss-120b`），`system`（可选系统提示），`maxTokens`（可选，64–16384，限制为模型的上限）。
## 示例
```jsonc
// list_providers
> {}
{
"ok": true,
"count": 18,
"available": 11,
"default_provider": "gpt-oss-120b",
"providers": [
{ "key": "gpt-oss-120b", "label": "GPT-OSS 120B", "network": "OpenAI · OpenRouter", "tier": "balanced", "maxOutput": 8192, "available": true, "requiresAuth": false },
{ "key": "claude-sonnet-4-6", "label": "Claude Sonnet 4.6", "network": "Anthropic", "tier": "balanced", "maxOutput": 16384, "available": true, "requiresAuth": true },
{ "key": "deepseek-r1", "label": "DeepSeek R1", "network": "DeepSeek", "tier": "reasoning", "maxOutput": 8192, "available": true, "requiresAuth": true }
/* … */
]
}
```
```jsonc
// chat
> {
"provider": "claude-sonnet-4-6",
"system": "You are terse.",
"messages": [{ "role": "user", "content": "Name three Solana RPC methods." }]
}
{
"ok": true,
"provider": "claude-sonnet-4-6",
"model": "Claude Sonnet 4.6",
"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-4-7`、`claude-sonnet-4-6` 和 `claude-haiku-4-5`，但实时列表才是准确的。
## 身份验证
| 模型类别 | 需要密钥？ |
| ---------------------------------------------------------------------------- | --------------------------- |
| 免费开放权重层级（GPT-OSS 120B，NVIDIA NIM：Nemotron / Kimi / Llama 4） | 否 |
| 付费第一方旗舰模型（Claude，GPT-4o，o3，Qwen Plus，DeepSeek，…） | 是 — 设置 `THREE_WS_API_KEY` |
在 [three.ws/account](https://three.ws/account) 创建 API 密钥。没有它，付费模型将返回登录错误，`list_providers` 将标记它们为 `requiresAuth: true`。
## 要求
- **Node.js >= 20.**
- 可以访问 `https://three.ws`（或您自己的 `THREE_WS_BASE`）。
### 环境变量
| 变量 | 是否必需 | 默认值 | 用途 |
| --------------------- | -------- | ------------------ | ---------------------------------------------------------------- |
| `THREE_WS_BASE` | 否 | `https://three.ws` | API 基地址（覆盖以自托管或目标预览）。 |
| `THREE_WS_API_KEY` | 否 | — | 解锁付费第一方旗舰模型的 Bearer 凭证。 |
| `THREE_WS_TIMEOUT_MS` | 否 | `120000` | 每请求超时（补全流式服务器端）。 |
## 链接
- 首页：https://three.ws
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
Copyright © 2026 nirholas. All rights reserved.
本软件为专有软件 — 见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
