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
CLI command	ai-router
GitHub	scriptkid23/ai-router

Quick start

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), 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	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

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 if the commands above fail. On Unix, pipx ensurepath usually adds ~/.local/bin to your shell PATH.

Verify:

ai-router --version
ai-router --help

Upgrade later:

pipx upgrade mcp-ai-router

Uninstall:

pipx uninstall mcp-ai-router
# optional manual cleanup:
# rm -rf ~/.ai-router ~/.cloakbrowser

Login (one-time)

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.

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:

{
  "mcpServers": {
    "ai-router": {
      "type": "stdio",
      "command": "ai-router",
      "args": ["serve"]
    }
  }
}

Claude Code — ~/.claude/settings.json:

{
  "mcpServers": {
    "ai-router": {
      "command": "ai-router",
      "args": ["serve"]
    }
  }
}

Claude Desktop — MCP config file for your OS (Anthropic docs); 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:

command -v ai-router    # macOS/Linux
where ai-router       # Windows

{
  "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

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):

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:

ai-router serve --transport http

{
  "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

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):

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.