Skip to main content
Glama
gemini-diagram-mcp

gemini-diagram-mcp

by arunsanna

gemini-diagram-mcp

npm version License: MIT

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)

Related MCP server: fcp-drawio

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

Available Tools

3 tools
generate_imageA

Generate a diagram, chart, or visualization using Gemini. Intelligently detects type from prompt and asks clarifying questions when uncertain. Supports: chart, comparison, flow, architecture, timeline, hierarchy, matrix, hero, visualization.

Inputs: prompt (required), size, type, style, +4 more.

prepare_imageA

Get guidance before generating an image. Call this FIRST to understand supported parameters, get prompt recommendations, and receive a polished prompt. This avoids rejected generations and wasted API calls.

Inputs: type, prompt.

refine_imageA

Refine the last generated image with modifications

Inputs: refinement (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: prepare for guidance, generate for creation, and refine for modification. There is no overlap in functionality, making it easy for an agent to select the right tool.

    Naming Consistency5/5

    All tool names follow the same verb_noun pattern with underscores: prepare_image, generate_image, refine_image. This consistent naming convention makes the tool set predictable and easy to navigate.

    Tool Count5/5

    With only three tools, the server is well-scoped for its purpose of diagram generation. Each tool covers an essential step in the workflow without unnecessary bloat, and the count is appropriate for a focused utility.

    Completeness5/5

    The tool set covers the full generation lifecycle: prepare, generate, and refine. This provides a complete workflow for users, and there are no obvious missing operations that would cause agent failures.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers