@fre4x/gemini

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	Image synthesis via Imagen 4 (imagen-4.0-generate-001). Optionally save to output_dir.
generate_video	Async video generation via Veo (veo-3.1-generate-preview). Returns operation_name to poll.
get_video_status	Poll video generation status. Returns URLs when complete. Optionally saves to output_dir.

Requirements

A Google AI Studio API key — set as GEMINI_API_KEY.

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 requires Imagen access — not available on all free-tier API keys. Check AI Studio.
• Video generation is async. Call generate_video → poll get_video_status every ~30s until done: true.
• analyze_media accepts file:// paths for local files and auto-detects MIME type from URL extension (jpg, png, mp4, mp3, wav, pdf, etc.). If you omit prompt, it defaults to "Describe this media." and uses gemini-2.5-flash by default.
• analyze_media rejects retired text-model aliases such as gemini-1.5-* and gemini-2.0-*. If you override model, use a currently supported generateContent model.
• output_dir on generate_image and get_video_status saves 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.