9Router MCP
<h1 align="center">9Router MCP</h1>
<h3 align="center">Unofficial MCP server for 9Router</h3>

Use your 9Router search, fetch, chat, vision, image, speech, embedding, and video capabilities from an MCP client. The server runs over stdio and forwards requests to your configured 9Router instance. Provider credentials, quotas, and fallback combinations are managed in 9Router.
```mermaid
flowchart LR
A[MCP client] -->|stdio| B[9Router MCP]
B -->|HTTP or HTTPS| C[Your 9Router instance]
C --> D[Configured providers]
```
## Installation
Requires Node.js 22 or later and a running [9Router](https://github.com/decolua/9router). Connect the providers you want to use in the 9Router dashboard.
### Install with your agent
Once the GitHub repository is public, paste this prompt into your coding agent from any workspace. The agent will clone the repository, build the server, and configure your current harness.
```text
Install the unofficial 9Router MCP server into my current agent harness.
Clone https://github.com/lucian-voss/9router-mcp into a persistent folder
outside my current project. If there is already a checkout for that GitHub
repository, reuse it and preserve any local changes. If GitHub is
unreachable or the repository isn't accessible, report the error before
changing any harness settings.
In the checkout, check for Node.js 22 or newer, then run npm ci and
npm run build. Use the matching host example in its README.md to configure
a stdio server named ninerouter using node and the absolute path to the
checkout's dist/cli.js. Preserve my existing MCP servers and settings.
If you can't identify the harness or which config to edit, ask me.
Use http://localhost:20128 unless I specify a different 9Router URL. If my
gateway requires NINEROUTER_KEY, use an existing environment variable or
the host's secret store. Keep its value out of chat and shared config.
Verify the host can discover ninerouter_health and call it if available.
Report where you installed it, which config you changed, and any checks
you couldn't complete.
```
### Update with your agent
Paste this prompt into your coding agent from any workspace to update an existing source installation to the latest published `main` commit.
```text
Update the unofficial 9Router MCP server used by my current agent harness.
Find the ninerouter entry in the harness configuration and use the path to
dist/cli.js to locate the installed checkout. Verify its origin is
https://github.com/lucian-voss/9router-mcp. If you can't identify the
installation or it uses a different source, ask me before changing anything.
Record the current commit and fetch origin. If the checkout has local edits,
is off main, or has commits ahead of or diverging from origin/main, report
what you found and ask before proceeding. Otherwise, update main with
git merge --ff-only origin/main. Preserve my harness config and credentials.
With Node.js 22 or newer, run npm ci, npm run build, and
node dist/cli.js --version in that checkout. Reload the MCP server if the
harness supports it, then verify it can discover and call ninerouter_health.
If a restart is required, tell me instead of closing my active session.
Report the previous and current commits and which checks passed.
```
### Install manually from source
```sh
npm ci
npm run build
node dist/cli.js --version
```
Use `node` with the absolute path to `dist/cli.js` in your MCP host. This checkout also builds an npm tarball with `npm pack`. After installing that tarball, `mcp-9router-gateway` is the executable.
### npm registry
`mcp-9router-gateway` is currently unpublished. Once a release is published, the MCP host can launch it with `npx -y mcp-9router-gateway@0.1.0`, assuming `0.1.0` is the published version. Pinning the version keeps the host on the release you verified.
## Set up a host
The examples use a local gateway with authentication disabled. For a different gateway, set `NINEROUTER_URL` in the server environment. For an authenticated gateway, set `NINEROUTER_KEY` through your host's environment configuration or secret store. Keep keys out of shared configuration files. Replace `/absolute/path/to/dist/cli.js` with the real path.
### Claude Code
```sh
claude mcp add --scope user --transport stdio ninerouter -- node /absolute/path/to/dist/cli.js
claude mcp list
```
### Codex
```toml
[mcp_servers.ninerouter]
command = "node"
args = ["/absolute/path/to/dist/cli.js"]
env_vars = ["NINEROUTER_URL", "NINEROUTER_KEY"]
```
Add this to your Codex `config.toml` and start Codex with any required variables set.
### OpenCode 2.x
```json
{
"mcp": {
"servers": {
"ninerouter": {
"type": "local",
"command": ["node", "/absolute/path/to/dist/cli.js"]
}
}
}
}
```
Add this to `opencode.json` and run `opencode mcp list`. OpenCode 1.x uses entries directly under `mcp` and a different configuration schema.
### OpenClaw
```sh
openclaw mcp set ninerouter '{"command":"node","args":["/absolute/path/to/dist/cli.js"]}'
openclaw mcp probe ninerouter
```
### Hermes Agent
```yaml
mcp_servers:
ninerouter:
command: node
args:
- /absolute/path/to/dist/cli.js
```
Add this entry to your Hermes `config.yaml` and run `hermes mcp test ninerouter`. See [Hermes MCP setup](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) for per-server environment variables and secret handling.
## Usage
Start with `ninerouter_health` and `ninerouter_list_models`. Pick an ID that matches the operation, then pass it to the tool. For example, call `ninerouter_web_search` with `{"model":"exa/search","query":"Model Context Protocol specification","max_results":5}` if your gateway advertises that model. Use `ninerouter_model_info` for model-specific parameters.
For web tools, the server translates a catalog ID such as `exa/search` or `firecrawl/fetch` to the provider alias expected by the gateway.
| Capability | Tools, with the `ninerouter_` prefix |
| --------------- | -------------------------------------------------------------- |
| Discovery | `health`, `list_models`, `model_info`, `list_voices` |
| Research | `web_search`, `web_fetch` |
| Chat and vision | `chat`, `count_tokens`, `compact_response` |
| Media | `generate_image`, `text_to_speech`, `transcribe_audio` |
| Embeddings | `embed` |
| Video | `generate_video`, `edit_video`, `extend_video`, `video_status` |
For binary images and speech, the server emits MCP media content. Image URL mode works for clients that cannot display native images. Transcription accepts base64 input and sends a multipart upload. Omit `language` when using `cx/transcribe`. Video submission returns a `job` object. Pass that object to `video_status` to poll on the originating provider connection. Upstream SSE and Ollama JSON lines are collected into a bounded result.
### Configuration
| Environment variable | Default | Purpose |
| --------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `NINEROUTER_URL` | `http://localhost:20128` | Gateway base URL, optionally ending in `/v1`. A reverse-proxy prefix is preserved. |
| `NINEROUTER_KEY` | unset | Gateway bearer key when authentication is enabled. |
| `NINEROUTER_TIMEOUT_MS` | `120000` | Request deadline, including response body reads. Set the host's tool timeout accordingly. |
| `NINEROUTER_MAX_BYTES` | `8388608` | Maximum upstream request or response body size. MCP serialization and media base64 can increase the final message size. |
| `NINEROUTER_MAX_CONCURRENT` | `4` | In-flight requests per server process. |
| `NINEROUTER_TOOLS` | all tools | Comma-separated allowlist of full tool names. |
See [compatibility and known limits](docs/compatibility.md) and [security](SECURITY.md).
## Development
```sh
npm run typecheck
npm test
npm pack --dry-run
```
The integration tests launch the compiled server and use a local mock gateway. They require no provider accounts or paid requests.
TDQS
Scored across 17 tools
Most tools target clearly distinct operations across chat, embeddings, media, search, and utility tasks. The closest overlap is between list_models and model_info, and among the video job tools, but their descriptions provide enough separation to select correctly.
All tools share a consistent ninerouter_ prefix and snake_case naming. Most names use an action-oriented verb_noun pattern, with a few noun-based read/status names such as health, model_info, and video_status as minor deviations.
Seventeen tools is somewhat heavy but justified by the broad multi-modal gateway scope: chat, models, embeddings, images, video, speech, transcription, web access, and token utilities. Each tool maps to a meaningful capability rather than duplicating another.
The surface covers the main AI gateway workflows well, including model discovery, chat, embeddings, media generation, speech, transcription, web search/fetch, and health checks. Minor gaps exist around lifecycle operations such as canceling or listing video jobs and possible provider/model management, but agents can work around these.