内容
AI 路由器
AI 路由器是一个 Python 标准输入输出的 MCP 服务器。安装 PyPI 上的 **`mcp-ai-router`** 包，运行-router`** 命令行界面，并使用 `"command": "ai-router `"args": ["serve"]` 连接任何 MCP 客户端。
它通过 CloakBrowser 自动进行身份验证的 **Gemini** 和 **ChatGPT** 网页会话 —— **无需 API 密钥**，但您需要提供商的网页账户和一次性命令行界面登录。
| |
|---|------|
| **PyPI / pipx** | [`mcp-ai-router`](https://pypi.org/project/mcp-ai-router/) |
| **命令行界面命令** | `ai-router` |
| **GitHub** | [scriptkid23/ai-router](github.com/scriptkid23/ai-router) |
## 快速开始
```bash
pipx install mcp-ai-router # 1
ai-router browser login # 2. 登录（打开浏览器窗口）
ai-router browser status # 3. 预期 gemini/chatgpt: logged_in
```
添加 MCP 配置（参见 [连接 MCP 客户端](#连接mcp客户端)），重新加载客户端，然后验证：
> 向代理询问： *"调用 list_providers，然后要求 Gemini 准确回复：router working"*
## 要求
| 工具 | 版本 |
|------|---------|
| Python | 3.11+ |
| [pipx](https://pypa.github.io/pipx/) | 最新版本 |
| 磁盘 + 网络 | ~ 空间用于首次浏览器下载 |
在 **macOS**、**Linux** 和 **Windows** 上测试通过。正常使用 stdio需 Poetry、Node.js 或仓库克隆。
**提供商账户：** 有效的或 ChatGPT 网页账户（免费层）。登录需通过浏览器界面手动完成。
## 安装
```bash
python3 -m pip install --user pipx # 如有必要，在 Windows 上使用 py -m pip
python3 -m pipx ensurepath
# 打开新的终端
pipx install mcp-ai-router
```
如果上述命令失败，请参阅 [pipx 安装文档](https://pypa.io/stable/installation/)。在 Unix 上，`pipx ensurepath会将 `~/.local/bin` shell PATH 中。
验证：
```bash
ai-router --version
ai-router --help
```
升级：
```bash
pipx upgrade mcp-ai-router
```
卸载：
```bash
pipx uninstall mcp-ai-router
# 可选清理：
# rm -ai-router ~/.cloak```
## 登录（
```bash
ai-router browser login #用的提供商
browser login --provider
ai-router browser login --provider chatgpt
```
1. 可见的浏览器窗口打开（每个正在配置商一个）。
2. 在每个窗口中使用您的提供商账户登录。
3. 完成时关闭 **所有** 浏览器窗口 ——将会话保存到磁盘中。
会话存储在/.ai-router/profile/` 中。仅登录到商也可以；使用-router browser status` 检查。
```bash
ai status
# gemini: logged_in
# chat logged_in
```
> **CloakBrowser 下载使用）
> `pipx install` **不** 下载浏览器。首次 `browser login` 或 `ask` 触发一次性下载 CloakBrowser 管理的 Chromium 二进制文件（~200 MB `~/.cloakbrowser/`。您 **不** 需要 `playwright install` 或单独的 —— 自动化使用 CloakBrowser 二进制文件，而不是您的本地 Chrome 应用程序。
## 连接 MCP 客户端
与支持 std任何 MCP 客户端配合使用 —— **Cursor**、**Claude Code**、**Claude Desktop** 等。
**Cursor** —— `~/.cursor/mcp.json` 或项目 `.cursor/mcp.json`:
```json
{
"mcpServers": {
"ai-router": {
"type": "stdio",
"command": "ai-router "args": ["serve"]
}
}
}
```
**Claude —— `~/.claude/settings.json`:
```json
{
"mcp {
"ai-router": {
"command": "ai-router",
"args": ["serve"]
}
}
}
```
**Claude Desktop** —— 适用于您操作系统的 MCP 配置文件Anthropic 文档](https://docs.anthropic.com/build-with-claude/mcp)）；相同的 `command` / `args`。
客户端启动 `ai-router serve`（stdio，默认单独的终端，无需 Node.js。
#### 如果 `"command": "ai-router"` GUI 应用程序通常使用不同的 PATH。使用以下命令获取绝对路径：
```bash
command -v ai-router # macOS/Linux
where ai-router # Windows
```
```json
{
"mcpServers": {
"ai-router": "type": "stdio "command": "/绝对/到/ai-router",
"args": ["serve"]
}
}
```
在 JSON 中使用完整的绝对路径 —— 不要使用 `~`（大多数扩展它）。
在保存后重新加载客户端的 MCP MCP 工具
| 工具 | 描述 |
|------|-------------|
| `ask(prompt, provider?)` | 发送提示；默认提供商是 Gemini。设置 `provider` 为 `"chatgpt使用 ChatGPT。 |
ask_multi(prompt, providers?, strategy?)` | 并行多个提供商（`strategy`：`all`、`first`、`longest`）。 |
| `list_providers()`出提供商和状态。 |
| `session_status(provider?)` | 在不打开聊天的情况下检查登录状态。 |
登录限命令行界面** —— 运行 `ai-router browser login`；没有 MCP 登录工具对话行为：** ask` 打开一个新的提供聊天。后续上下文在不保留。您的 MCP 客户端线程和提供商的是分开的。
**并发性：** 一个 MCP 服务器进程通过页面队列处理请求。对同一提供商的并发` 调用可能会返回 `BROWSER_BUSY` —— 请等待。`ask_multi` 在一个服务器内并行发送到多个提供商。
## 命令行界面参考
```bash-router --version
ai-router serve [--transport stdio|http] [--host 127.0.0.1] [--port 8087]
ai-router browser login [--provider gemini|chatgpt]
ai-router browser status [--provider gemini|]
```
| 传输 | 用例 |
|-----------|----------|
| `stdio`（默认） | MCP 客户端 —— `"args": ["serve"]` |
| `http` | 仅限本地调试 —— 参见下文 |
## 配置（可选）
创建 `~/.ai-router/config.yaml`。值与内置默认值合并（ChatGPT 保持启用，除非您覆盖 URL）：
```yaml
default_provider: gemini
host: 127.0.0.1
port: 8087
answer_timeout_s: 120
profile_dir: ~/.ai-router/profile
providers:
gemini:
url: https://gem.com/app
chatgpt:
url: https://chatgpt.com/
```
优先级：环境变量覆盖 YAML；YAML 覆盖默认值。
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `AI_ROUTER_PROFILE_DIR` | `~/.ai-router/profile` | 浏览器配置文件目录 |
| `AI_ROUTER_DEFAULT_PROVIDER` | `gemini` | `ask` 的默认提供商 |
| `AI_ROUTER_HOST` | `127.0.0.1` | HTTP 绑定地址 |
| `AI_ROUTER_PORT` | `8087` | HTTP 端口 |
| `AI_ROUTER_ANSWER_TIMEOUT_S` | `120` | 每个请求的超时时间（秒） |
## 故障排除
| 问题 | 解决方法 |
|---------|-----|
| `pipx: command not found` | 使用 `python3 -m pipx` |
| `ai-router: command not found` | 运行 `pipx ensurepath`，打开新的终端 |
| MCP 客户端无法找到 `ai-router` `"command"` 中使用绝对路径 |
| `pipx install mcp-ai-router` 失败 | 检查 Python ≥ 3.11 并访问 https://pypi.org/project/mcp-ai-router/ |
| `gemini: logged_out` / `NOT_LOGGED_IN` | 运行 `ai-router browser login` |
| 登录或首次 `ask` 速度慢 | CloakBrowser 下载约 200 MB，或浏览器启动缓慢 |
| 浏览器未打开 | 需要网络 + 磁盘；需要 `cloakbrowser` ≥ 0.4.4 |
| `BROWSER_BUSY` | 另一个请求正在进行中 —— 请等待并重试 |
| 配置文件锁定 / 浏览器错误 | 每个配置文件只有一个 MCP 服务器；重启客户端以清除过时的进程 |
| 需要 HTTP 调试 | `ai-router serve --transport http` |
### HTTP 调试（高级）
stdio MCP 不需要。 在终端中运行服务器，然后使用 Node.js 进行桥接：
```bash
ai-router serve --transport http
```
```json
{
"mcpServers": {
"ai-router": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "http://127.0.0.1:8087/mcp"]
}
}
}
```
HTTP 仅绑定到 localhost 且 **无身份验证** —— 请勿将其暴露在您的机器之外。
## 开发
```bash
git clone https://github.com/scriptkid23/ai-router.git
cd ai-router
poetry install
poetry run pytest -v
poetry run ruff check src tests
poetry run ai-router serve --transport http
```
测试 wheel（macOS/Linux 示例）：
```bash
poetry build
pipx install --force dist/mcp_ai_router-*.whl
mkdir -p /tmp/ai-router-smoke && cd /tmp/ai-router-smoke
ai-router --help && ai-router --version && ai-router browser status
```
## 安全
- 提示发送到 Gemini/ChatGPT **网页界面** —— 提供商的隐私和条款适用。请查看每个提供商的条款；网页自动化可能会违反某些账户政策。
- `~/.ai-router/profile/` 保存活动会话 cookie —— 请像对待密码一样保护它。删除它会在本地注销您。
- 日志可能会写入 `~/.ai-router/logs/` 和 stderr。
- HTTP 调试模式绑定到 `127.0.0.1` 且无身份验证 —— 仅限 localhost。
## 许可证
MIT —— 参见 [LICENSE](LICENSE)。
