maagpi-images-mcp

Google AI Studio image MCP — generate images with Imagen 4 and Gemini (Nano Banana family) and describe images with Gemini Vision, usable from Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Gemini CLI, and any MCP-compatible client.

Transparent sibling fallback kicks in when a tier-gated or rate-limited model fails, so a single call can degrade gracefully across gemini-3-pro-image-preview → gemini-3.1-flash-image-preview → gemini-2.5-flash-image → imagen-4.0-generate-001.

Server

• Transports: stdio (default), streamable-http (optional, for shared/team setups)
• Distribution: npx (no install), global npm, or local clone
• Runtime: Node.js 18+

Authentication

Set a Google AI Studio API key as GOOGLE_AI_API_KEY — either in the client's env block or in a local .env file.

Keep your API key secret. Never commit it to source control. .env is already in .gitignore.

Quick Connect

All snippets below use the npx form, which fetches and runs the server on demand with no install step. To pin a specific version, use maagpi-images-mcp@<version> (e.g. [email protected]).

If you've cloned the repo locally, swap command: "npx" + args: ["-y", "maagpi-images-mcp"] for command: "node" + args: ["--env-file=/abs/path/.env", "/abs/path/dist/index.js"].

Claude Code

Project-scoped (.mcp.json at the repo root, already included in this repo for local dev):

{
  "mcpServers": {
    "maagpi-images-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "maagpi-images-mcp"],
      "env": { "GOOGLE_AI_API_KEY": "your_key_here" }
    }
  }
}

Or register globally via the CLI:

claude mcp add maagpi-images-mcp \
  --env GOOGLE_AI_API_KEY=your_key_here \
  -- npx -y maagpi-images-mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "maagpi-images-mcp": {
      "command": "npx",
      "args": ["-y", "maagpi-images-mcp"],
      "env": { "GOOGLE_AI_API_KEY": "your_key_here" }
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "maagpi-images-mcp": {
      "command": "npx",
      "args": ["-y", "maagpi-images-mcp"],
      "env": { "GOOGLE_AI_API_KEY": "your_key_here" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "maagpi-images-mcp": {
      "command": "npx",
      "args": ["-y", "maagpi-images-mcp"],
      "env": { "GOOGLE_AI_API_KEY": "your_key_here" }
    }
  }
}

VS Code

.vscode/mcp.json in your workspace (or via the MCP: Add Server command):

{
  "servers": {
    "maagpi-images-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "maagpi-images-mcp"],
      "env": { "GOOGLE_AI_API_KEY": "your_key_here" }
    }
  }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "maagpi-images-mcp": {
      "command": "npx",
      "args": ["-y", "maagpi-images-mcp"],
      "env": { "GOOGLE_AI_API_KEY": "your_key_here" }
    }
  }
}

HTTP transport (shared / team setups)

Run the server in HTTP mode:

GOOGLE_AI_API_KEY=your_key_here \
MCP_TRANSPORT=http \
MCP_HTTP_PORT=3000 \
MCP_HTTP_HOST=127.0.0.1 \
  npx -y maagpi-images-mcp

Health check: GET http://127.0.0.1:3000/health returns { "status": "ok", ... }.

Then point a client at it:

{
  "mcpServers": {
    "maagpi-images-mcp": {
      "url": "http://127.0.0.1:3000/mcp",
      "transport": "streamable-http"
    }
  }
}

The HTTP transport has no built-in auth. Bind to 127.0.0.1 (the default) or place it behind a reverse proxy that enforces authentication before exposing it beyond localhost — anyone who can reach /mcp will spend your Google AI quota.

Tool Reference

| Tool | Parameters | Description | |---|---|---| | generate_image | prompt, model?, numberOfImages?, aspectRatio?, outputFormat?, safetyFilterLevel?, outputPath?, disableFallback? | Text-to-image via Imagen 4 or Gemini image models, with transparent sibling fallback on tier/rate-limit errors | | describe_image | imagePath, question? | Describe or answer questions about a local image via Gemini Vision |

generate_image

| Parameter | Type | Required | Description | |---|---|---|---| | prompt | string | yes | Text description of the image to generate (max 2000 chars) | | model | string | no | One of the supported models (default: gemini-2.5-flash-image) | | numberOfImages | number | no | 1–4 (default: 1) | | aspectRatio | string | no | 1:1, 16:9, 9:16, 4:3, 3:4 — Imagen 4 only | | outputFormat | string | no | PNG (default), JPEG, or WEBP | | safetyFilterLevel | string | no | BLOCK_LOW_AND_ABOVE / BLOCK_MEDIUM_AND_ABOVE / BLOCK_ONLY_HIGH / BLOCK_NONE — Imagen 4 only | | outputPath | string | no | Absolute path to save the file. Use {index} for multiple images. If omitted, returns base64. | | disableFallback | boolean | no | If true, surface the original error instead of falling back to a sibling model on MODEL_NOT_FOUND / PERMISSION_DENIED / RATE_LIMITED / QUOTA_EXCEEDED. |

Fallback chain: if the requested model fails with a fallback-eligible error, the tool transparently retries with gemini-3-pro-image-preview → gemini-3.1-flash-image-preview → gemini-2.5-flash-image → imagen-4.0-generate-001. Each fallback hop is recorded in the response warnings array so you know which model actually produced the output.

describe_image

| Parameter | Type | Required | Description | |---|---|---|---| | imagePath | string | yes | Absolute path to the image (PNG, JPEG, or WEBP) | | question | string | no | Specific question about the image. If omitted, returns a detailed general description. |

Supported models (Google AI Studio, 2026)

| Model | Notes | |---|---| | gemini-2.5-flash-image | Default. Nano Banana — fast, cheap, supports editing | | gemini-3-pro-image-preview | Nano Banana Pro — 4K studio quality. Tier 1+ paid only (10 IPM) | | gemini-3.1-flash-image-preview | Nano Banana 2 — high-efficiency Gemini 3 image | | imagen-4.0-generate-001 | Imagen 4 standard | | imagen-4.0-fast-generate-001 | Imagen 4 fast (cheapest) | | imagen-4.0-ultra-generate-001 | Imagen 4 ultra (highest quality) |

Imagen 3 (imagen-3.0-*) was shut down by Google and is no longer accepted. Image editing is not supported on AI Studio Imagen — use a Gemini image model for edits.

Example

stdio (JSON-RPC over stdin)

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_image","arguments":{"prompt":"a red panda astronaut, studio lighting","outputPath":"/tmp/panda.png"}}}' \
  | GOOGLE_AI_API_KEY=your_key_here npx -y maagpi-images-mcp

HTTP (curl)

curl -s -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "generate_image",
      "arguments": {
        "prompt": "a red panda astronaut, studio lighting",
        "outputPath": "/tmp/panda.png"
      }
    }
  }'

Environment Variables

| Variable | Default | Description | |---|---|---| | GOOGLE_AI_API_KEY | — | Required. Google AI Studio API key | | MCP_TRANSPORT | stdio | Transport mode: stdio or http | | MCP_HTTP_PORT | 3000 | HTTP server port (http transport only) | | MCP_HTTP_HOST | 127.0.0.1 | HTTP server host (http transport only) | | MCP_LOG_LEVEL | info | Log verbosity: error, warn, info, debug | | NODE_ENV | production | Node environment |

Development

git clone https://github.com/vamsi-kodimela/maagpi-images-mcp.git
cd maagpi-images-mcp
npm install
cp .env.example .env   # set GOOGLE_AI_API_KEY

npm run dev          # run with tsx (no build needed)
npm run typecheck    # TypeScript type check
npm test             # run tests
npm run test:watch   # watch mode
npm run build        # compile to dist/

Why maagpi-images-mcp

• Multi-model with transparent fallback — tier-gated gemini-3-pro-image-preview falls back to siblings on PERMISSION_DENIED / RATE_LIMITED / QUOTA_EXCEEDED so calls keep working when a paid-only model is unavailable.
• One API key, three modalities — Imagen 4 generation, Gemini image generation, and Gemini Vision describe — all under a single GOOGLE_AI_API_KEY.
• Structured errors — every failure carries an error code, a retryable flag, a suggested fix, and (when relevant) a retryAfterMs hint, so clients can recover cleanly.
• stdio or HTTP — local single-user setups via stdio; shared / team / containerized setups via streamable HTTP, with a /health endpoint for ops.

Links

• Repo: https://github.com/vamsi-kodimela/maagpi-images-mcp
• Google AI Studio (API keys): https://aistudio.google.com/apikey
• MCP specification: https://modelcontextprotocol.io
• Imagen 4 model card: https://ai.google.dev/gemini-api/docs/imagen
• Gemini image generation: https://ai.google.dev/gemini-api/docs/image-generation

License

MIT