ImageRouter

Local MCP image-generation router for xAI/Grok, Antigravity, and OpenAI Codex with ordered fallback, a local Playground, and an OpenAI-compatible image endpoint.

ImageRouter is a local image-generation control plane for developer tools and AI agents. It exposes two MCP tools that route requests through configured xAI, Antigravity, and OpenAI Codex accounts.

ImageRouter v1 is intentionally narrow:

• One image per request.
• MCP over stdio and Streamable HTTP.
• POST /v1/images/generations for REST clients.
• Ordered provider and account fallback.
• No gallery, image cache, prompt history, chat, audio, video, search, or CLI integrations.
• Prompts pass through unchanged. The prompt pipeline is a no-op extension point for a later template/enhancer phase.

Connector status

Provider	Status	Authentication	Notes
xAI / Grok	Stable	API key or OAuth	Uses the published xAI Images API.
Antigravity	Experimental	OAuth or manual token	Uses a private Code Assist endpoint that may change.
OpenAI Codex	Experimental	OAuth or manual token	Uses a private ChatGPT Codex Responses endpoint and requires an eligible account.

Experimental connector failures are isolated to their route attempt; they do not crash the MCP server.

Requirements

• Node.js 20 or newer.
• A supported provider account.
• A local MCP client for MCP usage.

Quick start

Download and install

Requirements: Node.js 20+ and git.

Windows PowerShell, macOS, and Linux:

git clone https://github.com/Duylamneuuu/imagerouter.git
cd imagerouter
npm install

Optional local environment file:

# macOS/Linux
cp .env.example .env.local

# Windows PowerShell
Copy-Item .env.example .env.local

The environment file is optional for the normal dashboard flow. Do not commit .env.local; it is ignored by Git. Antigravity OAuth reconnect/refresh additionally requires the two IMAGEROUTER_ANTIGRAVITY_* variables described below.

Run the dashboard

npm run dev

Open http://127.0.0.1:20127, then:

1. Add one or more accounts on Providers.
2. Test each account.
3. Arrange the provider chain on Routing.
4. Reveal the HTTP token on Settings if an HTTP client needs it.

Production mode:

npm run build
npm run start

Both commands bind only to 127.0.0.1. The saved dashboard port is applied on restart; IMAGEROUTER_PORT overrides it.

Run the full local quality check:

npm run check

MCP

stdio

Run the protocol launcher directly:

npm run mcp:stdio

Example client configuration:

{
  "mcpServers": {
    "imagerouter": {
      "command": "npm",
      "args": ["run", "mcp:stdio"],
      "cwd": "C:/absolute/path/to/ImageRouter"
    }
  }
}

The stdio launcher writes MCP protocol frames to stdout and diagnostics to stderr.

Streamable HTTP

Endpoint:

http://127.0.0.1:20127/mcp

Send the token shown in Settings:

Authorization: Bearer <ImageRouter token>

Example client configuration:

{
  "mcpServers": {
    "imagerouter": {
      "url": "http://127.0.0.1:20127/mcp",
      "headers": {
        "Authorization": "Bearer ${IMAGEROUTER_TOKEN}"
      }
    }
  }
}

Tools

generate_image accepts:

{
  "prompt": "A precise image prompt",
  "provider": "auto",
  "model": "xai/grok-imagine-image-quality",
  "reference_images": [],
  "aspect_ratio": "16:9",
  "output_path": "C:/optional/output.png",
  "overwrite": false
}

• provider defaults to auto.
• model may be a plain model override or provider/model, which pins that provider.
• Without output_path, image bytes are returned only in the MCP response.
• With output_path, exactly one file is written atomically. Existing files are protected unless overwrite is true.

The response contains an MCP image block, a short text summary, and structured route metadata. get_image_router_status returns routes, capabilities, and redacted account health; it never returns credentials.

REST compatibility

curl http://127.0.0.1:20127/v1/images/generations \
  -H "Authorization: Bearer $IMAGEROUTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "prompt": "A cobalt technical illustration on white paper",
    "response_format": "b64_json"
  }'

model accepts auto or provider/model. JSON responses follow the OpenAI image shape and add a router object with the actual provider/model and attempts. Set response_format to binary, or send Accept: image/*, to receive raw image bytes.

Routing semantics

• The first enabled route is the default.
• auto exhausts enabled accounts for a provider in account-priority order before moving to the next route.
• An explicit provider still tries its other accounts but never falls back to another provider.
• Cross-provider fallback occurs only for timeout, network, quota/rate-limit, token-refresh, capacity, and upstream 5xx failures.
• Invalid prompts/parameters, safety rejection, output-path errors, and capability mismatch do not cross-fallback.
• In auto, an incompatible route is recorded as skipped and the next compatible route is tried.

Local data and privacy

Default data locations:

• Windows: %APPDATA%/ImageRouter
• macOS/Linux: ~/.imagerouter

Set IMAGEROUTER_DATA_DIR to use another location. ImageRouter never reads or modifies a legacy profile.

SQLite stores:

• encrypted provider credentials;
• route and account order;
• runtime settings;
• activity timestamp, provider/model, duration, status, fallback count, error code, and optional output path.

SQLite does not store prompts, image blobs, image base64, or generated previews. The Playground creates a temporary browser object URL and revokes it when replaced or unmounted.

The HTTP server binds to loopback, validates the Host and browser Origin, and requires a local bearer token on /mcp and /v1/images/generations.

Environment

See .env.example.

Variable	Default	Purpose
IMAGEROUTER_DATA_DIR	Platform data directory	SQLite and credential-vault location.
IMAGEROUTER_PORT	Saved setting or 20127	Local dashboard, MCP HTTP, and REST port.
IMAGEROUTER_MAX_BODY_SIZE	32mb	Next.js request body ceiling.
IMAGEROUTER_PLAYWRIGHT_EXECUTABLE_PATH	Auto-detected local browser	Optional existing Chromium/Chrome executable for E2E.
IMAGEROUTER_ANTIGRAVITY_CLIENT_ID	Empty	OAuth client ID for reconnecting Antigravity accounts.
IMAGEROUTER_ANTIGRAVITY_CLIENT_SECRET	Empty	OAuth client secret for reconnecting Antigravity accounts; never commit it.

Development and tests

npm run lint
npm test
npm run build
npm run test:e2e

E2E uses an already-installed Chromium/Chrome executable when one is available; the test command does not install a browser.

Real-provider smoke tests are opt-in and may incur provider charges:

npm run test:smoke

They remain skipped unless the matching IMAGEROUTER_SMOKE_* credentials are present.

Architecture

server/providers/   xAI, Antigravity, Codex adapters
server/image/       validation, capabilities, routing, artifacts
server/mcp/         shared MCP factory, HTTP and stdio transports
server/rest/        OpenAI-compatible image endpoint
server/db/          minimal SQLite schema and encrypted credentials
src/app/            six-screen local workbench
tests/              unit, integration, E2E and opt-in smoke tests

Attribution

ImageRouter is an independent rewrite. Portions of the Antigravity and Codex adapter behavior were derived from the MIT-licensed decolua/9router project. See NOTICE.md for provenance.

License

MIT. See LICENSE.