gemini — The Intelligence Bridge
The agent that can see, hear, and imagine is the agent that cannot be outmaneuvered.
Part of FRE4X-B1TE — a monorepo of MCP servers built for autonomous agents.
Google's Gemini is not a chatbot. It is a multimodal reasoning engine. This B1TE bridges your agent directly to that engine — text, images, video, audio — so it can perceive the world as humans do, and then outthink it.
Tools
| Tool | Capability |
|---|---|
analyze_media | Analyze an image or audio file via URL or file:// path. Prompt is optional. |
list_models | List supported models for analyze_media, generate_image, and generate_video. Filter by analyze, image, video, or all. |
generate_image | Nano Banana image synthesis via generateContent with imageConfig.aspectRatio. Optionally save to output_dir. |
generate_video | Start async Gemini Omni video generation via the REST Interactions API (gemini-omni-1.1-flash by default). Returns an interaction id to poll. |
get_video_status | Single GET status check per call (returns done: false while queued/in_progress). Set wait=true to block until complete or timeout. Downloads via Files API when ready. Optionally saves to output_dir. |
Requirements
A Google AI Studio API key — set as GEMINI_API_KEY.
Environment variables
| Variable | Purpose |
|---|---|
GEMINI_API_KEY | Required for live API calls (unless MOCK=true). |
GEMINI_IMAGE_MODEL | Override default image model (gemini-3.1-flash-image). |
GEMINI_VIDEO_MODEL | Override default Omni video model (gemini-omni-1.1-flash). |
GEMINI_VIDEO_POLL_TIMEOUT_MS | Max wait when get_video_status.wait=true (default 600000 ms). |
GEMINI_MEDIA_FETCH_TIMEOUT_MS | Per-request timeout for Interactions/Files HTTP calls (default 30000 ms). |
Polling interval for in-progress video is GEMINI_VIDEO_POLL_INTERVAL_MS (5 seconds) when using wait=true or Files API processing.
Mock Mode
Run without an API key (returns fixture data of identical shape):
MOCK=true npx @fre4x/gemini
Deploy
{
"mcpServers": {
"gemini": {
"command": "npx",
"args": ["-y", "@fre4x/gemini"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}
Notes
- Image generation uses Nano Banana
generateContentwithresponseModalities: ["IMAGE"]andimageConfig.aspectRatio(not Imagen). Check AI Studio for model access. - Video generation uses the Interactions API with
x-goog-api-keyheader auth (never?key=on URLs). Flow:generate_video→ callget_video_statusevery ~5s untildone: true, or passwait=trueon a status check to block until complete. - Tool errors include
recovery_class:agent_recoverable(retry with corrected params/models) vsuser_action_required(moderation, auth, quota,requires_action). analyze_mediaacceptsfile://paths for local files and auto-detects MIME type from URL extension (jpg, png, mp4, mp3, wav, pdf, etc.). If you omitprompt, it defaults to "Describe this media." and usesgemini-3.8-flashby default.analyze_mediarejects retired text-model aliases such asgemini-1.5-*andgemini-2.0-*. If you overridemodel, use a currently supportedgenerateContentmodel.output_dirongenerate_imageandget_video_statussaves files to disk. Directory is created if it doesn't exist.- Model defaults are intentionally pinned to the latest verified official Gemini docs for the current date. Do not replace them with older names from stale model knowledge.
Development
npm install
npm run dev # tsx, no build
npm run build # esbuild → dist/
npm test # vitest unit tests
npm run inspector # MCP inspector in mock mode
License
MIT — WE ARE THE FRE4X.