gemini-diagram-mcp

MCP server for generating diagrams, charts, and visualizations using Gemini image generation on Vertex AI.

Features

• Smart Detection: Auto-detects diagram type from prompt, asks clarifying questions when uncertain
• Universal: Works with Claude Code, Claude Desktop, Cursor, Windsurf, Cline, and any MCP client
• Two Style Modes: professional (clean SaaS aesthetic) and creative (vintage, comic, dark theme, etc.)
• Configurable: Aspect ratios (16:9, 1:1, 4:3, 9:16, 21:9, and more) and resolutions (1K, 2K, 4K)
• Custom Watermark: Configurable watermark text rendered on every image
• Iterative Refinement: Refine the last generated image without repeating the full prompt
• Pre-generation Guidance: prepare_image tool returns prompt recommendations before you generate
• Comic/Story Pattern: Built-in stock character (Alex) and comic art style for multi-panel storytelling
• Robust: Retry logic with exponential backoff, generated image validation, dimension mismatch warnings
• Three Deployment Modes: Local stdio, centralized HTTP server, or stdio proxy to remote server
• Auth: Static bearer token, OIDC JWT, or no-auth (behind trusted proxy)

Tools

Tool	Description
generate_image	Generate a diagram/chart/visualization from natural language
refine_image	Iteratively refine the last generated image
prepare_image	Get guidance, supported parameters, and a polished prompt before generating

Parameters

generate_image

Parameter	Type	Default	Description
prompt	string	required	Natural language description of the image
output	string	auto	Output filename (auto-generated from prompt if omitted)
type	enum	auto	auto, chart, comparison, flow, architecture, timeline, hierarchy, matrix, hero, visualization
aspect_ratio	enum	auto	16:9, 1:1, 4:3, 3:4, 9:16, 3:2, 2:3, 21:9 (auto-selected by type if omitted)
size	enum	2K	1K (~1024px), 2K (~2048px), 4K (~4096px)
style	enum	professional	professional (clean SaaS aesthetic) or creative (your prompt drives the look)
watermark	string	arunsanna.com	Watermark text in the bottom-right corner
user_approval	boolean	false	Set true when the requester explicitly approves using supplied architecture details for diagramming

refine_image

Parameter	Type	Description
refinement	string	Description of changes to apply to the last generated image

prepare_image

Parameter	Type	Description
prompt	string	Optional draft prompt to analyze and polish
type	string	Optional type hint to get specific guidance

Installation

1. Get API Key

Get a Vertex AI API key for the Vertex AI Express Mode flow. The server enforces vertexai: true and defaults to gemini-3-pro-image-preview (Nano Banana Pro).

2. Choose How You Run It

You can run this MCP in three ways:

1. Local stdio server (classic MCP): each client spawns npx gemini-diagram-mcp and you provide the Vertex AI API key to the client.
2. Centralized HTTP server (recommended for teams): run one Docker container with the API key + auth (static token or OIDC), and have clients connect via a local proxy (no API key on clients).
3. CLI one-shot: npx gemini-diagram-mcp generate "your prompt" to generate directly from the command line.

Centralized Deployment (Docker)

This runs one MCP server that all agents share.

Requirements

• VERTEX_AI_API_KEY (preferred) or GOOGLE_API_KEY / GOOGLE_CLOUD_API_KEY
• GOOGLE_GENAI_USE_VERTEXAI=true is enforced by the server
• VERTEX_AI_IMAGE_MODEL=gemini-3-pro-image-preview by default (see Supported Models)
• Auth (choose one):
  • Static token (default): MCP_AUTH_MODE=token + MCP_AUTH_TOKEN (or MCP_AUTH_TOKENS)
  • OIDC JWT (recommended for multi-user): MCP_AUTH_MODE=oidc + OIDC_ISSUER (+ OIDC_AUDIENCE recommended)
  • No auth (not recommended): MCP_AUTH_MODE=none (only safe behind a trusted auth proxy / private network)

Suggested .env

VERTEX_AI_API_KEY=your-vertex-ai-api-key

# Auth (choose one)
MCP_AUTH_MODE=token
MCP_AUTH_TOKEN=your-strong-token

# Or: OIDC JWT auth (per-user tokens)
# MCP_AUTH_MODE=oidc
# OIDC_ISSUER=https://issuer.example.com/realms/your-realm
# OIDC_AUDIENCE=your-audience
# OIDC_JWKS_URI=https://issuer.example.com/.../jwks.json

Run

export VERTEX_AI_API_KEY="your-vertex-ai-api-key"
export MCP_AUTH_MODE="token"
export MCP_AUTH_TOKEN="your-strong-token"
docker compose up --build

Outputs are written to ./data/out on the host (via bind mount).

The MCP endpoint will be:

• Streamable HTTP: http://localhost:3000/mcp
• Legacy SSE: http://localhost:3000/sse

All endpoints require auth. Depending on your auth mode:

Static token mode (MCP_AUTH_MODE=token):

• Authorization: Bearer $MCP_AUTH_TOKEN (recommended), or
• ?token=$MCP_AUTH_TOKEN (useful for clients that can't set headers)

OIDC JWT mode (MCP_AUTH_MODE=oidc):

• Authorization: Bearer <OIDC access token>
• ?token=... is disabled by default in oidc mode; set MCP_ALLOW_QUERY_TOKEN=1 to allow it (not recommended)

Client Setup (Local Proxy)

For MCP clients that expect command/args (Claude Code, Claude Desktop, VS Code integrations, etc.), run the included stdio proxy so the client talks stdio but execution happens on the central server.

Set environment:

• MCP_REMOTE_URL (default: http://localhost:3000/mcp)
• MCP_BEARER_TOKEN (required; OIDC access token or static token)

Example (Claude Code):

claude mcp add-json gemini-image '{
  "command":"npx",
  "args":["gemini-diagram-mcp","proxy"],
  "env":{
    "MCP_REMOTE_URL":"http://localhost:3000/mcp",
    "MCP_BEARER_TOKEN":"your-bearer-token"
  }
}'

Example (Claude Desktop):

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["gemini-diagram-mcp", "proxy"],
      "env": {
        "MCP_REMOTE_URL": "http://localhost:3000/mcp",
        "MCP_BEARER_TOKEN": "your-bearer-token"
      }
    }
  }
}

Example (VS Code / Cline):

{
  "gemini-image": {
    "command": "npx",
    "args": ["gemini-diagram-mcp", "proxy"],
    "env": {
      "MCP_REMOTE_URL": "http://localhost:3000/mcp",
      "MCP_BEARER_TOKEN": "your-bearer-token"
    }
  }
}

Other MCP clients (Codex CLI, opencode, etc.):

If your client supports configuring an MCP server with command + args + env, use the same proxy config:

• command: npx
• args: ["gemini-diagram-mcp","proxy"]
• env: MCP_REMOTE_URL, MCP_BEARER_TOKEN

Local (Classic) Installation

No build required — just use npx:

Claude Code

claude mcp add-json gemini-image '{"command":"npx","args":["gemini-diagram-mcp"],"env":{"VERTEX_AI_API_KEY":"your-vertex-ai-api-key"}}'

Or manually edit ~/.claude.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["gemini-diagram-mcp"],
      "env": {
        "VERTEX_AI_API_KEY": "your-vertex-ai-api-key"
      }
    }
  }
}

Cursor

Add to Cursor settings (Preferences > MCP Servers):

{
  "gemini-image": {
    "command": "npx",
    "args": ["gemini-diagram-mcp"],
    "env": {
      "VERTEX_AI_API_KEY": "your-vertex-ai-api-key"
    }
  }
}

Windsurf

Add to ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["gemini-diagram-mcp"],
      "env": {
        "VERTEX_AI_API_KEY": "your-vertex-ai-api-key"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["gemini-diagram-mcp"],
      "env": {
        "VERTEX_AI_API_KEY": "your-vertex-ai-api-key"
      }
    }
  }
}

Cline (VS Code)

Add to Cline MCP settings in VS Code:

{
  "gemini-image": {
    "command": "npx",
    "args": ["gemini-diagram-mcp"],
    "env": {
      "VERTEX_AI_API_KEY": "your-vertex-ai-api-key"
    }
  }
}

3. Restart Your Client

Restart the application to load the MCP server.

CLI Usage

Generate images directly from the command line:

export VERTEX_AI_API_KEY="your-key"
npx gemini-diagram-mcp generate "Architecture: React → API Gateway → Lambda → DynamoDB"
npx gemini-diagram-mcp generate "Sales funnel chart" -t chart --size 4K --style creative
npx gemini-diagram-mcp generate "Vintage poster for a coffee shop" --style creative -o poster.png

Usage Examples

User: "Create an architecture diagram showing React → API Gateway → Lambda → DynamoDB"
AI: → Generated architecture (4:3, 2K, style: professional): ./react_api_gateway.png

User: "Make the arrows thicker and add a Redis cache layer"
AI: → Refined image: ./react_api_gateway_refined.png

User: "Compare latency: 450ms before vs 120ms after optimization"
AI: → Generated comparison (16:9, 2K): ./latency_comparison.png

User: "A vintage travel poster for Tokyo, art deco style"
AI: → Tip: set style: "creative" to remove professional constraints
AI: → Generated hero (16:9, 2K, style: creative): ./vintage_tokyo.png

User: "Create a nice visual for my presentation"
AI: "I'm not certain about the best visualization type. What type would you prefer?
     - chart: Data visualization with clear labels
     - comparison: Side-by-side panels
     - flow: Sequential stages with arrows
     - architecture: System components with connections
     ..."

Smart Detection

The server auto-detects optimal settings from your prompt:

Keyword	Detected Type	Aspect Ratio
"compare", "vs", "before/after"	comparison	16:9
"flow", "process", "pipeline"	flow	16:9
"architecture", "system", "layers"	architecture	4:3
"timeline", "roadmap", "phases"	timeline	16:9
"hierarchy", "org chart", "tree"	hierarchy	4:3
"matrix", "grid", "quadrant"	matrix	1:1
"presentation", "slide", "4k"	(any)	4K resolution
"square"	(any)	1:1
"wide", "banner", "header"	(any)	16:9
"portrait", "mobile", "story"	(any)	9:16

Style Modes

Mode	Description
professional (default)	White background, SaaS color palette, sans-serif fonts, clean enterprise look
creative	No aesthetic constraints — your prompt controls colors, fonts, backgrounds, and artistic effects

Keywords like "vintage", "comic", "dark theme", "watercolor", "retro", "sketch" automatically trigger a tip to switch to creative mode.

Supported Models

Model ID	Codename	Tier	Best For
gemini-3-pro-image-preview	Nano Banana Pro	Pro (default)	Complex diagrams, high-fidelity text rendering, professional assets. Uses reasoning ("Thinking").
gemini-3.1-flash-image-preview	Nano Banana 2	Flash	Speed, high-volume, low-latency use cases. Supports 0.5K–4K resolution.
gemini-2.5-flash-image	Nano Banana	Flash (legacy)	Cheapest, basic image generation.

Set via VERTEX_AI_IMAGE_MODEL environment variable.

Architecture

src/
├── index.ts              # CLI entry point (stdio / http / proxy / generate)
├── http.ts               # Centralized HTTP MCP server (Streamable HTTP + legacy SSE)
├── proxy.ts              # Stdio proxy that forwards to a remote HTTP MCP server
├── stdio.ts              # Classic stdio MCP server
├── mcp.ts                # MCP tool registration (shared across all modes)
├── auth.ts               # Authentication middleware (token / OIDC JWT / none)
├── runtime.ts            # Environment config, version, model defaults
├── gemini/
│   ├── index.ts          # Module exports
│   └── client.ts         # Gemini API client with smart detection & prompt engineering

How It Works

1. Smart Analysis: analyzePrompt() scores prompt against type keywords, returns confidence level
2. Clarifying Questions: Low confidence → returns question instead of generating
3. Prompt Enhancement: Wraps prompt with style instructions (professional or creative) + watermark
4. Technical Diagrams: Architecture/flow types get visual vocabulary injection (cylinders for DBs, pipes for queues, etc.)
5. Image Generation: Uses Vertex AI mode with @google/genai SDK
6. Retry Logic: 3 attempts with exponential backoff (1s → 2s → 4s)
7. Image Validation: Verifies generated bytes (PNG/JPEG/WebP/GIF), correct extension, dimensions
8. Session Tracking: In-memory per MCP connection/session (suitable for centralized servers)

Deployment Modes

┌──────────────┐     stdio      ┌──────────────────┐
│  MCP Client  │◄──────────────►│  stdio server     │  (local, classic)
│ (Claude/etc) │                │  (npx ... )       │
└──────────────┘                └──────────────────┘

┌──────────────┐     stdio      ┌──────────────┐    HTTP     ┌──────────────────┐
│  MCP Client  │◄──────────────►│  stdio proxy │◄──────────►│  HTTP server     │
│ (Claude/etc) │                │  (npx proxy) │            │  (Docker/forge)  │
└──────────────┘                └──────────────┘            └──────────────────┘

┌──────────────┐                                            ┌──────────────────┐
│  CLI         │───────────────────────────────────────────►│  Gemini API      │
│  (generate)  │                                            │  (Vertex AI)     │
└──────────────┘                                            └──────────────────┘

Environment Variables

Variable	Default	Description
VERTEX_AI_API_KEY	—	Vertex AI API key (preferred)
GOOGLE_API_KEY	—	Backward-compatible alias
GOOGLE_CLOUD_API_KEY	—	Backward-compatible alias
VERTEX_AI_IMAGE_MODEL	gemini-3-pro-image-preview	Model for image generation
MCP_AUTH_MODE	token	Auth mode: token, oidc, none
MCP_AUTH_TOKEN	—	Static bearer token(s)
MCP_AUTH_TOKENS	—	Comma-separated multiple tokens
OIDC_ISSUER	—	OIDC issuer URL (required for oidc mode)
OIDC_AUDIENCE	—	Expected token audience(s)
OIDC_JWKS_URI	—	Override JWKS URI (skips discovery)
MCP_ALLOW_QUERY_TOKEN	1 (token mode)	Allow ?token=... query param auth
MCP_REMOTE_URL	http://localhost:3000/mcp	Proxy remote URL
MCP_BEARER_TOKEN	—	Proxy auth token
HOST	0.0.0.0	HTTP server bind host
PORT	3000	HTTP server bind port
OUTPUT_DIR	./data/out	Output directory for generated images
PUBLIC_BASE_URL	http://localhost:$PORT	Base URL for download links
INLINE_IMAGES	0	Include base64 image data in tool responses
MCP_SESSION_TIMEOUT_MIN	30	Session timeout in minutes
MCP_MAX_SESSIONS	100	Maximum concurrent sessions
ALLOWED_HOSTS	—	Comma-separated allowed host headers

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

License

MIT