Content
# AI Router
AI Router is a Python stdio MCP server. Install the **`mcp-ai-router`** package from PyPI, run the **`ai-router`** CLI, and connect any MCP client with `"command": "ai-router"` and `"args": ["serve"]`.
It automates authenticated **Gemini** and **ChatGPT** web sessions through CloakBrowser — **no API keys**, but you do need provider web accounts and a one-time CLI login.
| | Name |
|---|------|
| **PyPI / pipx** | [`mcp-ai-router`](https://pypi.org/project/mcp-ai-router/) |
| **CLI command** | `ai-router` |
| **GitHub** | [scriptkid23/ai-router](https://github.com/scriptkid23/ai-router) |
## Quick start
```bash
pipx install mcp-ai-router # 1. install
ai-router browser login # 2. log in (opens browser windows)
ai-router browser status # 3. expect gemini/chatgpt: logged_in
```
Add MCP config (see [Connect MCP client](#connect-mcp-client)), reload your client, then verify:
> Ask your agent: *"Call list_providers, then ask Gemini to reply with exactly: router working"*
## Requirements
| Tool | Version |
|------|---------|
| Python | 3.11+ |
| [pipx](https://pypa.github.io/pipx/) | latest |
| Disk + network | ~200 MB free for first browser download |
Tested on **macOS**, **Linux**, and **Windows**. No Poetry, Node.js, or repo clone required for normal stdio MCP use.
**Provider accounts:** valid Gemini and/or ChatGPT web accounts (free tiers work). Login is manual via the browser UI.
## Install
```bash
python3 -m pip install --user pipx # use py -m pip on Windows if needed
python3 -m pipx ensurepath
# open a new terminal
pipx install mcp-ai-router
```
See [pipx installation docs](https://pypa.io/stable/installation/) if the commands above fail. On Unix, `pipx ensurepath` usually adds `~/.local/bin` to your shell PATH.
Verify:
```bash
ai-router --version
ai-router --help
```
Upgrade later:
```bash
pipx upgrade mcp-ai-router
```
Uninstall:
```bash
pipx uninstall mcp-ai-router
# optional manual cleanup:
# rm -rf ~/.ai-router ~/.cloakbrowser
```
## Login (one-time)
```bash
ai-router browser login # all available providers
ai-router browser login --provider gemini
ai-router browser login --provider chatgpt
```
1. Visible browser windows open (one per provider being configured).
2. Log in with your provider account in each window.
3. Close **all** browser windows when done — this saves the session to disk.
Sessions are stored in `~/.ai-router/profile/`. Logging in to one provider only is fine; use `ai-router browser status` to check.
```bash
ai-router browser status
# gemini: logged_in
# chatgpt: logged_in
```
> **CloakBrowser download (first use)**
> `pipx install` does **not** download the browser. The first `browser login` or `ask` triggers a one-time download of a CloakBrowser-managed Chromium binary (~200 MB) to `~/.cloakbrowser/`. You do **not** need `playwright install` or a separate Chrome install — automation uses the CloakBrowser binary, not your local Chrome app.
## Connect MCP client
Works with any MCP client that supports stdio — **Cursor**, **Claude Code**, **Claude Desktop**, and others.
**Cursor** — `~/.cursor/mcp.json` or project `.cursor/mcp.json`:
```json
{
"mcpServers": {
"ai-router": {
"type": "stdio",
"command": "ai-router",
"args": ["serve"]
}
}
}
```
**Claude Code** — `~/.claude/settings.json`:
```json
{
"mcpServers": {
"ai-router": {
"command": "ai-router",
"args": ["serve"]
}
}
}
```
**Claude Desktop** — MCP config file for your OS ([Anthropic docs](https://docs.anthropic.com/en/docs/build-with-claude/mcp)); same `command` / `args`.
The client spawns `ai-router serve` (stdio, default). No separate terminal, no Node.js.
#### If `"command": "ai-router"` fails
GUI apps often use a different PATH than your terminal. Use the absolute path from:
```bash
command -v ai-router # macOS/Linux
where ai-router # Windows
```
```json
{
"mcpServers": {
"ai-router": {
"type": "stdio",
"command": "/absolute/path/to/ai-router",
"args": ["serve"]
}
}
}
```
Use a full absolute path in JSON — do not use `~` (most clients do not expand it).
Reload MCP in your client after saving.
## MCP tools
| Tool | Description |
|------|-------------|
| `ask(prompt, provider?)` | Send a prompt; default provider is Gemini. Set `provider` to `"chatgpt"` for ChatGPT. |
| `ask_multi(prompt, providers?, strategy?)` | Fan out to multiple providers in parallel (`strategy`: `all`, `first`, `longest`). |
| `list_providers()` | List providers and status. |
| `session_status(provider?)` | Check login state without opening a chat. |
Login is **CLI only** — run `ai-router browser login` manually; there is no MCP login tool.
**Conversation behavior:** each `ask` opens a **new** provider web chat. Follow-up context is not preserved across calls. Your MCP client's thread and the provider's web chat are separate.
**Concurrency:** one MCP server process handles requests through a page queue. Concurrent `ask` calls to the same provider may return `BROWSER_BUSY` — wait and retry. `ask_multi` fans out across providers in parallel within one server.
## CLI reference
```bash
ai-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|chatgpt]
```
| Transport | Use case |
|-----------|----------|
| `stdio` (default) | MCP clients — `"args": ["serve"]` |
| `http` | Local debugging only — see below |
## Config (optional)
Create `~/.ai-router/config.yaml`. Values merge with built-in defaults (ChatGPT stays enabled unless you override URLs):
```yaml
default_provider: gemini
host: 127.0.0.1
port: 8087
answer_timeout_s: 120
profile_dir: ~/.ai-router/profile
providers:
gemini:
url: https://gemini.google.com/app
chatgpt:
url: https://chatgpt.com/
```
Precedence: environment variables override YAML; YAML overrides defaults.
| Variable | Default | Description |
|----------|---------|-------------|
| `AI_ROUTER_PROFILE_DIR` | `~/.ai-router/profile` | Browser profile directory |
| `AI_ROUTER_DEFAULT_PROVIDER` | `gemini` | Default provider for `ask` |
| `AI_ROUTER_HOST` | `127.0.0.1` | HTTP bind address |
| `AI_ROUTER_PORT` | `8087` | HTTP port |
| `AI_ROUTER_ANSWER_TIMEOUT_S` | `120` | Per-request timeout (seconds) |
## Troubleshooting
| Problem | Fix |
|---------|-----|
| `pipx: command not found` | Use `python3 -m pipx` |
| `ai-router: command not found` | Run `pipx ensurepath`, open a new terminal |
| MCP client cannot find `ai-router` | Use absolute path in `"command"` |
| `pipx install mcp-ai-router` fails | Check Python ≥ 3.11 and https://pypi.org/project/mcp-ai-router/ |
| `gemini: logged_out` / `NOT_LOGGED_IN` | Run `ai-router browser login` |
| Slow first login or first `ask` | CloakBrowser downloading ~200 MB, or cold browser start |
| Browser does not open | Needs network + disk; requires `cloakbrowser` ≥ 0.4.4 |
| `BROWSER_BUSY` | Another request is in progress — wait and retry |
| Profile lock / browser errors | Only one MCP server per profile; restart client to clear stale processes |
| Need HTTP debug | `ai-router serve --transport http` |
### HTTP debug (advanced)
Not needed for stdio MCP. Run the server in a terminal, then bridge with 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 binds to localhost only and has **no authentication** — do not expose it beyond your machine.
## Development
```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
```
Smoke-test a wheel (macOS/Linux example):
```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
```
## Security
- Prompts are sent to Gemini/ChatGPT **web UIs** — provider privacy and terms apply. Review each provider's terms; web automation may violate some account policies.
- `~/.ai-router/profile/` holds live session cookies — treat like a password. Deleting it logs you out locally.
- Logs may be written to `~/.ai-router/logs/` and stderr.
- HTTP debug mode binds to `127.0.0.1` with no auth — localhost only.
## License
MIT — see [LICENSE](LICENSE).
