Omni Ai

omni-ai-mcp

Google Gemini's full toolbox, plus 400+ models via OpenRouter, as one MCP server for Claude. Video, music, voice, images, deep research, a managed coding agent, 1M-token analysis and more: Claude stays the orchestrator and calls them as tools.

You → Claude Code / Claude Desktop
        └─ omni-ai-mcp (28 tools)
             ├─ Gemini API ── Gemini 4 Argon · 3.8 Flash · Nano Banana · Omni Flash · Lyria · 3.8 TTS · Transcribe
             │                Deep Research · Antigravity agent · Embedding 2 · Robotics ER · File Search
             └─ OpenRouter ── GPT, Claude, Llama, Mistral, Grok, DeepSeek, Qwen, Perplexity… (400+)

Contents

Why · What's new · Install · Tools · Examples · Models · Configuration · Claude Code plugin · Docker · Troubleshooting · Costs · Development · Security

Why

Claude is excellent at reasoning and code. Some jobs need what only Google ships, or a second opinion from another model family:

• Generate and edit media: video with native audio (Gemini Omni Flash), images up to 4K with readable text (Nano Banana), full songs with vocals (Lyria), studio-grade speech in hundreds of voices (Gemini 3.8 TTS)
• Understand media: diarized transcripts, YouTube and long-video analysis, image OCR, spatial reasoning
• Research: Google-grounded search with citations, autonomous Deep Research reports from dozens of sources
• Delegate work: the Antigravity agent runs code, edits files and browses the web in its own Google-hosted sandbox
• Scale context: analyse a whole codebase in Gemini's 1M-token window
• Retrieve: RAG over your documents, multimodal embeddings for semantic search
• Compare: ask any of 400+ models through one tool

Models are auto-detected from the live API: when Google ships a newer Flash, Pro, image, TTS or video model, the server uses it on the next refresh, with no release of this package.

What's new in 4.8

Everything Google shipped in the Gemini API from June to October 2026, except the real-time Live API models. Verified live with one real call per tool.

• Gemini 4 Argon is the new pro. Gemini Omni Flash replaces Veo for video (Veo 3.1 Preview was shut down in the Gemini API on 2026-10-22).
• Nano Banana 2.1 and 2 Lite for images, Gemini 3.8 TTS with the Voice Library, voice design and voice replication.
• Seven new tools: video understanding, music, three voice tools, multimodal embeddings, the Antigravity agent. Plus Deep Research Max, Robotics ER and Gemma 4.
• 4.8.2 is a security release: every file a tool reads or writes now stays inside the workspace, credentials are always refused, and OpenRouter calls retry on transient errors. See Security.

Full history: CHANGELOG.md.

Install

You need a Gemini API key (get one) and, optionally, an OpenRouter key (openrouter.ai) for non-Google models.

Claude Code: one command (recommended)

With uv installed, nothing else is needed: uvx fetches the package from PyPI with a suitable Python.

claude mcp add omni-ai-mcp --scope user \
  -e GEMINI_API_KEY=YOUR_GEMINI_KEY \
  -e OPENROUTER_API_KEY=YOUR_OPENROUTER_KEY \
  -- uvx omni-ai-mcp

Drop the OPENROUTER_API_KEY line if you only use Gemini. Restart Claude Code and check with claude mcp list. To pick up a new release, run uv cache clean omni-ai-mcp (or register uvx omni-ai-mcp@latest, which checks PyPI at every start).

Claude Desktop: one-click extension

1. Download omni-ai-mcp-vX.Y.Z.dxt from Releases
2. Double-click it (or drag it into Claude Desktop)
3. Paste your Gemini key (OpenRouter is optional)

Claude Code plugin

The plugin bundles the MCP server with the slash commands and subagents. Download omni-ai-mcp-plugin-vX.Y.Z.zip from Releases and install it from Claude Code, or run /setup inside a clone of this repository.

pip

pip install omni-ai-mcp      # Python 3.10+
omni-ai-mcp-setup            # interactive wizard: writes the server into ~/.claude.json

From source (contributors)

git clone https://github.com/marmyx77/omni-ai-mcp.git && cd omni-ai-mcp
./setup.sh YOUR_GEMINI_KEY [YOUR_OPENROUTER_KEY]

setup.sh creates a virtualenv in ~/.claude-mcp-servers/omni-ai-mcp, installs the checkout in editable mode (a git pull is the whole update) and registers the server in Claude Code.

Another machine, pinned to a release

For a home server or second workstation that should run a specific GitHub release:

curl -fsSL https://raw.githubusercontent.com/marmyx77/omni-ai-mcp/main/scripts/install_release.sh | bash             # latest tag
curl -fsSL https://raw.githubusercontent.com/marmyx77/omni-ai-mcp/main/scripts/install_release.sh | bash -s vX.Y.Z   # a specific tag

It picks a Python ≥ 3.10 (installing one with uv if needed), installs the tag into ~/.claude-mcp-servers/omni-ai-mcp/venv and points ~/.claude.json at it, keeping any API keys already configured (or reading GEMINI_API_KEY / OPENROUTER_API_KEY from the environment). --status compares the installed version with the latest tag.

The 28 tools

Text and reasoning

Code and agents

Research

Media

Examples

In Claude Code you ask in plain language and Claude picks the tool. The calls below show what it sends.

Second opinion from another model family

ask_model(prompt="Review this auth flow for security issues: …", model="openai/gpt-4o")
ask_model(prompt="Same question", model="pro")                    # newest Gemini flagship
ask_model(prompt="Fact-check with sources", model="perplexity/sonar-pro")

Deep research that survives timeouts

gemini_deep_research(query="Compare open-source vector databases for 100M embeddings", depth="max")
gemini_deep_research(query="", continuation_id="v1_…")           # timed out? fetch the finished report

Video: generate, then edit conversationally

gemini_generate_video(prompt="A paper boat on a calm pond at dawn, gentle water sounds", resolution="1080p", duration=6)
gemini_generate_video(prompt="Make it night. Keep everything else the same.", continuation_id="v1_…")
gemini_generate_video(prompt="<FIRST_FRAME> <LAST_FRAME> slow dolly between the two shots", image_paths=["a.png", "b.png"])

Editing or extending an uploaded clip (≤ 10 s) is not available in the EEA, Switzerland and the UK; edits of generated clips are.

Images

gemini_generate_image(prompt="Infographic: how a heat pump works, labelled, flat style", model="pro", image_size="4K")
gemini_generate_image(prompt="Panorama of the Alps at sunset", model="flash", aspect_ratio="8:1", google_search=True)

Music and voice

gemini_generate_music(prompt="Upbeat Italian pop song about summer in Turin, female vocals, about 2 minutes")
gemini_list_voices(language_codes=["it-IT"], contexts=["Audiobook"])
gemini_text_to_speech(text="Benvenuti al podcast.", voice="Kore", style="warm, slow narration", language="it-IT")
gemini_text_to_speech(text="Host: Welcome!\nGuest: Thanks for having me!",
                      speakers=[{"name": "Host", "voice": "Charon", "style": "welcoming"}, {"name": "Guest", "voice": "Aoede"}])
gemini_design_voice(description="A calm Italian radio host in her 40s, warm and precise", language_code="it-IT")

Transcription and video understanding

gemini_transcribe_audio(audio_path="meeting.m4a", diarization=True, word_timestamps=True)
gemini_analyze_video(prompt="Key moments with MM:SS timestamps", youtube_url="https://www.youtube.com/watch?v=…")
gemini_analyze_video(prompt="When is pricing discussed?", video_path="webinar.mp4", processing="agentic")

Delegate to the Antigravity agent

gemini_agent_task(task="Download the last 12 months of ECB rates, chart them and save the chart as PNG", output_dir="./out")

Codebase, files and memory

gemini_analyze_codebase(prompt="Find architecture issues", files=["app/**/*.py"], analysis_type="architecture")
ask_gemini(prompt="Review @src/auth.py for injection risks")     # @file, @src/*.py, @src/**/*.ts, @.
ask_gemini(prompt="And how do I fix it?", continuation_id="…")   # follow-up with memory
ask_gemini(prompt="Long project kickoff", mode="cloud", title="Arch review")   # resumable for 55 days

Models

Every tool asks for a category, and the registry resolves it at runtime to the newest model your key can use:

Ranking: a newer naming scheme beats an older one (Gemini 4 codenames, Nano Banana), then higher version, then stable over preview. If Google stops listing a family while still serving it, known IDs are verified by name. Run gemini_list_models to see each resolution and where it came from, and set GEMINI_MODEL_* to pin one (Configuration).

Thinking: ask_gemini takes thinking_level auto (default), low, medium or high. Gemini 3+ always reasons, so auto is not zero. temperature is accepted for compatibility but only reaches Gemini 2.x, Gemma and OpenRouter models: Google deprecated sampling parameters from Gemini 3.6.

OpenRouter (via ask_model): any ID from openrouter.ai/models, for example openai/gpt-4o, anthropic/claude-sonnet-5.5, x-ai/grok-4.7, deepseek/deepseek-v4-pro, meta-llama/llama-4-maverick, mistralai/mistral-large-2512, perplexity/sonar-pro (web search with citations). Routing rules:

• provider="auto" (default): Gemini IDs and aliases go to the native API when GEMINI_API_KEY is set, otherwise to OpenRouter's google/… mirror. Any other ID goes to OpenRouter. No model means pro, or OPENROUTER_DEFAULT_MODEL without a Gemini key.
• provider="openrouter": always OpenRouter. Gemini IDs and aliases become google/<id>; no model means OPENROUTER_DEFAULT_MODEL.
• provider="gemini": native API only.
• An explicit Gemini ID is never swapped for Flash on a quota error; the aliases (pro, flash) are.

Configuration

All settings are environment variables, passed with -e in claude mcp add or in the env block of your MCP config.

* The folder the client started the server in, unless that is / or your home folder (Claude Desktop does this): then ~/omni-ai-workspace, created on first run. Set GEMINI_SANDBOX_ROOT to choose another folder.

Claude Code plugin

Slash commands live in .claude/commands/ and subagents in .claude/agents/. They are active when Claude Code runs inside this repository, ship in the plugin zip, or can be copied globally:

cp .claude/commands/*.md ~/.claude/commands/ && cp .claude/agents/*.md ~/.claude/agents/

Docker

The image runs the server over stdio as an unprivileged user and works with a read-only root filesystem.

docker build -t omni-ai-mcp .
claude mcp add omni-ai-mcp --scope user -- docker run -i --rm \
  -e GEMINI_API_KEY=YOUR_KEY \
  -v "$HOME/omni-workspace:/workspace" -v omni-ai-mcp-logs:/logs \
  --read-only --tmpfs /tmp omni-ai-mcp

Tools read and write files only under /workspace; logs and conversation memory live in the /logs volume. docker-compose.yml builds the same image with these limits.

Troubleshooting

Costs

You pay Google and OpenRouter directly; this server adds nothing. Gemini prices change often, so check ai.google.dev/pricing and openrouter.ai/models. Snapshot of the text models, per million tokens (input / output), as published on 2026-10-25:

Video, music, images, speech, Deep Research and the agent are priced per output or per run: start small (resolution="360p", model="clip", depth="standard").

Development

git clone https://github.com/marmyx77/omni-ai-mcp.git && cd omni-ai-mcp
python3 -m pip install -e ".[dev]"
python3 -m pytest tests/ -q                                   # hermetic: no API key, no network
GEMINI_API_KEY=… python3 scripts/smoke_live.py                # one real call per tool (cheap set)
GEMINI_API_KEY=… python3 scripts/smoke_live.py --expensive    # + video, music, research, agent
node virgilio/bin/cli.mjs check --config virgilio.config.json  # docs ↔ reality gate (CI-enforced)

How the code is organised, how to add a tool and how releases work: CONTRIBUTING.md and CLAUDE.md.

app/
├── server.py          FastMCP server: 28 @mcp.tool() registrations
├── core/              config, structured logging, security (sandbox, secrets, safe writes)
├── services/          Gemini client, model registry, Interactions helpers, OpenRouter, SQLite memory
├── tools/             text/ · code/ · media/ · web/ · rag/
├── schemas/           Pydantic input validation
└── utils/             @file expansion, token estimates
scripts/               install_release.sh · smoke_live.py · bump_version.sh · build_dxt.sh · build_plugin.sh
tests/                 unit/ and integration/ (hermetic)

Security

• Every path a tool reads, uploads or writes is resolved (symlinks included) and must stay inside GEMINI_SANDBOX_ROOT. That covers @file references, codebase analysis, media inputs and output_path
• Credentials and keys (~/.ssh, .env, *.pem, ~/.claude.json, cloud CLI configs…) are refused even with the sandbox off
• Outputs need an allowed extension and never go through a symlink; without output_path they land in a private folder with random names, which the tools can read back
• No tool writes agent instructions or hooks (CLAUDE.md, .mcp.json, .claude/, .git/, .vscode/…)
• Media downloads send the API key only to Google hosts over HTTPS, never across a redirect
• API keys and tokens are masked in logs and error messages; the installers write ~/.claude.json with mode 600
• LLM-generated XML is sanitized before parsing; tool inputs are validated with Pydantic
• Voice replication requires the speaker's recorded consent, which Google verifies

Report vulnerabilities privately as described in SECURITY.md.

Contributing and license

Contributions are welcome: read CONTRIBUTING.md and the Code of Conduct, then open an issue or a pull request.

MIT — see LICENSE.