How to add llm-router to Windsurf
Local-first LLM router for AI coding tools — routes prompts to the cheapest capable model with automatic provider fallback. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.
Last updated June 14, 2026 · 33★ · stdio · no auth
Windsurf config for llm-router
pip install llm-routing && llm-router install{
"mcpServers": {
"llm-router": {
"command": "llm-router",
"args": [
"install"
]
}
}
}Setup steps
- 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
- 2Paste the llm-router config below.
- 3Fill in placeholder secrets, then save.
- 4Click Refresh in the MCP panel.
- 5llm-router's tools become available to Cascade.
Before you start
- Python 3.10+
- An MCP host (Claude Code, Codex CLI, Gemini CLI, VS Code, or Cursor)
- Optional provider API keys (e.g. OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY) or a local Ollama instance (OLLAMA_BASE_URL); works with zero keys on Claude Code Pro/Max
What llm-router can do in Windsurf
llm_routeRoute a prompt to the most cost-effective capable model based on the active policy and provider chain.
llm_classifyClassify prompt complexity (heuristic or model-assisted) to drive routing decisions.
llm_autoAutomatic routing entry point used by hook-driven auto-routing.
llm_streamStream a routed model response.
llm_queryGeneral-purpose text query routed through the free-first chain (primary manual tool for MCP clients like VS Code/Cursor).
llm_codeCode-oriented generation routed to an appropriate coding model.
llm_analyzeAnalysis-oriented text task routed to a capable model.
llm_researchResearch-oriented query, optionally using web-grounded providers.
Security
Runs locally with no hosted proxy, telemetry, or account. API keys live in local files (.env or ~/.llm-router/config.yaml) and are never transmitted by the router; keys are scrubbed from structured logs. Usage logs are stored as UNENCRYPTED SQLite at ~/.llm-router/usage.db — use full-disk encryption if needed (chmod 700 ~/.llm-router, 600 config.yaml recommended). Prompts are sent to whichever provider the router selects, so review each provider's privacy policy. The router cannot prevent provider-level jailbreaks or prompt injection. Hook scripts are local, inspectable shell scripts in ~/.claude/hooks/.
llm-router + Windsurf FAQ
Where is the Windsurf config file?
Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the llm-router config there under the "mcpServers" key and restart the client.
Is llm-router safe to use with Windsurf?
Runs locally with no hosted proxy, telemetry, or account. API keys live in local files (.env or ~/.llm-router/config.yaml) and are never transmitted by the router; keys are scrubbed from structured logs. Usage logs are stored as UNENCRYPTED SQLite at ~/.llm-router/usage.db — use full-disk encryption if needed (chmod 700 ~/.llm-router, 600 config.yaml recommended). Prompts are sent to whichever provider the router selects, so review each provider's privacy policy. The router cannot prevent provider-level jailbreaks or prompt injection. Hook scripts are local, inspectable shell scripts in ~/.claude/hooks/.
Do I need API keys to use it?
No. It works with zero API keys on Claude Code Pro/Max subscriptions, where routing uses MCP tools that only call external models when beneficial. Adding provider keys (e.g. OPENROUTER_API_KEY) widens the routing chain and unlocks policies like cost_aggressive.
What is the PyPI package name?
The package is `llm-routing` (`pip install llm-routing`); the CLI command and GitHub repo are named `llm-router`. The older `claude-code-llm-router` package is deprecated and redirects to `llm-routing`.
How do I add it to a host other than Claude Code?
Run `llm-router install` (defaults to Claude Code) or pass a host flag: `--host codex`, `--host gemini-cli`, `--host vscode`, or `--host cursor`. Any MCP client can also use the manual tools such as `llm_query`.