aitherflow-models

MCP server for calling external AI models — OpenRouter, Google Gemini, and Ollama (local) — with full vision support for images and video.

Works with any MCP client: Claude Code CLI, Claude Desktop, or any other MCP-compatible tool.

What it does

Gives your AI assistant four tools:

Tool	Description
call_model	Send a text prompt to any configured model
call_vision	Analyze images or video with a vision-capable model
analyze_directory	Batch-analyze all media files in a directory
list_models	List all available models across providers

Providers

Provider	Type	API key required
OpenRouter	Cloud	Yes
Google Gemini	Cloud	Yes
Ollama	Local	No

API keys are stored securely in the system keyring (service: aitherflow), not in config files.

Vision support

Images

PNG, JPG, GIF, WebP, BMP

Video

MP4, MOV, AVI, MKV, MTS, MXF, R3D, WebM

Video processing depends on the provider:

• Google Gemini — native video upload (full video sent to API)
• OpenRouter / Ollama — frame extraction via ffmpeg (keyframes sent as images)

Quick start

1. Build

git clone https://github.com/aitherlab-dev/aitherflow-models.git
cd aitherflow-models
cargo build --release

The binary will be at target/release/aitherflow-models.

Optionally, copy it somewhere on your $PATH:

cp target/release/aitherflow-models ~/.local/bin/

2. Add to Claude Code

claude mcp add --scope user aitherflow-models /path/to/aitherflow-models

Or edit ~/.claude.json manually:

{
  "mcpServers": {
    "aitherflow-models": {
      "command": "/home/you/.local/bin/aitherflow-models",
      "env": {}
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "aitherflow-models": {
      "command": "/home/you/.local/bin/aitherflow-models",
      "env": {}
    }
  }
}

3. Use it

Start Claude Code and ask it to use an external model:

> Ask Gemini to summarize this document
> Use GPT-4o to analyze this screenshot
> List available models

Configuration

Models config

~/.config/aither-flow/external_models.json

Models are organized by provider. The config is created automatically on first run with sensible defaults. You can add, remove, or reorder models freely.

API keys

API keys are stored in the system keyring under the service name aitherflow. The server will prompt for keys when needed, or you can set them via your MCP client's environment variables:

Variable	Provider
OPENROUTER_API_KEY	OpenRouter
GEMINI_API_KEY	Google Gemini

Ollama runs locally and requires no API key.

Logging

Set RUST_LOG for verbose output:

RUST_LOG=aitherflow_models=debug

Requirements

• Rust 1.75+
• ffmpeg (for video frame extraction — required only for vision with non-Gemini providers)
• libdbus-dev (for system keyring access on Linux)

Linux (Ubuntu/Debian)

sudo apt install ffmpeg libdbus-1-dev

Linux (Arch)

sudo pacman -S ffmpeg dbus

macOS

brew install ffmpeg

How it works

Claude Code <--> aitherflow-models (stdio, JSON-RPC) <--> OpenRouter / Gemini / Ollama APIs
                                                    \--> ffmpeg (video frame extraction)

The server communicates via stdin/stdout using the MCP protocol (JSON-RPC over stdio). API calls run asynchronously via tokio. For video analysis with non-Gemini providers, ffmpeg extracts keyframes which are then sent as base64-encoded images.

Troubleshooting

"No API key found" — set the appropriate environment variable or store the key in the system keyring.

"ffmpeg not found" — install ffmpeg. Only needed for video analysis with OpenRouter or Ollama providers.

"Keyring error" — on Linux, ensure libdbus is installed and a secret service (like gnome-keyring or kwallet) is running.

Logs — stderr output goes to your MCP client's server logs. Set RUST_LOG=aitherflow_models=debug for verbose output.

License

MIT

Credits

Built by aitherlab. Part of the aitherflow project.