使用说明

双子图mcp

MCP服务器，用于在Vertex AI上使用Gemini图像生成来生成图表、图表和可视化。

特性

智能检测：自动从提示中检测图表类型，不确定时询问澄清问题
通用：适用于Claude Code、Claude Desktop、Cursor、Windsurf、Cline和任何MCP客户端
两种风格模式: professional （干净的SaaS美学）和 creative （复古、漫画、黑暗主题等）
可配置的：宽高比（16:9、1:1、4:3、9:16、21:9等）和分辨率（1K、2K、4K）
自定义水印：在每张图像上呈现可配置的水印文本
迭代优化：优化最后生成的图像，而不重复完整提示
预生成指南: prepare_image 工具在生成之前返回提示建议
漫画/故事模式：内置股票角色（亚历克斯）和漫画艺术风格，适合多面板讲故事
健壮：使用指数回退、生成图像验证、维度不匹配警告重试逻辑
三种部署模式：本地stdio、集中式HTTP服务器或远程服务器的stdio代理
认证：静态承载令牌、OIDC JWT或无身份验证（在受信任的代理后面）

工具

工具	说明
`generate_image`	从自然语言生成图表/图形/可视化
`refine_image`	迭代优化最后生成的图像
`prepare_image`	在生成之前，获取指导、支持的参数和精美的提示

参数

generate_image

参数	类型	默认值	说明
`prompt`	string	必填	图像的自然语言描述
`output`	string	auto	输出文件名（如果省略，则从提示符自动生成）
`type`	enum	`auto`	`auto`, `chart`, `comparison`, `flow`, `architecture`, `timeline`, `hierarchy`, `matrix`, `hero`, `visualization`
`aspect_ratio`	enum	自动	`16:9`, `1:1`, `4:3`, `3:4`, `9:16`, `3:2`, `2:3`, `21:9` （如果省略，则按类型自动选择）
`size`	enum	`2K`	`1K` （~1024px）， `2K` （~2048px）， `4K` （~4096px）
`style`	enum	`professional`	`professional` （干净的SaaS美学）或 `creative` （你的提示决定了外观）
`watermark`	字符串	`arunsanna.com`	右下角水印文本
`user_approval`	布尔值	`false`	设置 `true` 当请求者明确批准使用提供的架构细节进行图表绘制时

refine_image

参数	类型	说明
`refinement`	string	应用于上次生成的图像的更改描述

prepare_image

参数	类型	说明
`prompt`	string	可选草稿提示，用于分析和润色
`type`	string	可选类型提示以获取具体指导

安装

1.获取API密钥

获取Vertex AI快速模式流的Vertex AI API键。服务器强制执行 vertexai: true 默认为 gemini-3-pro-image-preview （Nano Banana Pro）。

2.选择运行方式

您可以通过三种方式运行此MCP：

本地stdio服务器（经典MCP）：每个客户端生成 npx gemini-diagram-mcp 并将Vertex AI API密钥提供给客户端。
集中式HTTP服务器（建议团队使用）：使用API密钥+auth（静态令牌或OIDC）运行一个Docker容器，并让客户端通过本地代理连接（客户端上没有API密钥）。
CLI一键: npx gemini-diagram-mcp generate "your prompt" 直接从命令行生成。

集中式部署（Docker）

这将运行一个所有代理共享的MCP服务器。

需求

VERTEX_AI_API_KEY （首选）或 GOOGLE_API_KEY / GOOGLE_CLOUD_API_KEY
GOOGLE_GENAI_USE_VERTEXAI=true 由服务器强制执行
VERTEX_AI_IMAGE_MODEL=gemini-3-pro-image-preview 默认情况下（请参见支持的模型)
身份验证（选择一个）：
- 静态令牌 （默认）： MCP_AUTH_MODE=token + MCP_AUTH_TOKEN （或 MCP_AUTH_TOKENS)
- OIDC JWT （建议多用户使用）： MCP_AUTH_MODE=oidc + OIDC_ISSUER (+ OIDC_AUDIENCE 推荐）
- 无身份验证 （不推荐）： MCP_AUTH_MODE=none （仅在受信任的身份验证代理/专用网络后安全）

建议 `.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

跑

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

输出被写入 ./data/out 在主机上（通过绑定挂载）。

MCP终点为：

流式HTTP： http://localhost:3000/mcp
传统苏格兰和南方能源公司： http://localhost:3000/sse

所有端点都需要身份验证。根据您的身份验证模式：

静态令牌模式 (MCP_AUTH_MODE=token):

Authorization: Bearer $MCP_AUTH_TOKEN （推荐），或
?token=$MCP_AUTH_TOKEN （对于无法设置标头的客户端很有用）

OIDC JWT模式 (MCP_AUTH_MODE=oidc):

Authorization: Bearer <OIDC access token>
?token=... 在oidc模式下默认禁用；集 MCP_ALLOW_QUERY_TOKEN=1 允许（不推荐）

客户端设置（本地代理）

对于期望 command/args （Claude Code、Claude Desktop、VS Code集成等），运行包含的stdio代理，这样客户端就可以与stdio对话，但执行发生在中央服务器上。

设置环境：

MCP_REMOTE_URL （默认值： http://localhost:3000/mcp)
MCP_BEARER_TOKEN （必填；OIDC访问令牌或静态令牌）

示例（克劳德代码）：

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"
  }
}'

示例（克劳德桌面）：

添加 claude_desktop_config.json:

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %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"
      }
    }
  }
}

示例（VS代码/临床）：

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

其他MCP客户端（Codex CLI、opencode等）：

如果您的客户端支持配置MCP服务器 command + args + env，使用相同的代理配置：

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

本地（经典）安装

无需构建，只需使用 npx:

克劳德代码

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

或手动编辑 ~/.claude.json:

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

光标

添加到光标设置(Preferences > MCP Servers):

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

帆板运动

添加 ~/.windsurf/mcp.json:

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

克劳德桌面

添加 claude_desktop_config.json:

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %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代码）

添加到VS代码中的临床MCP设置：

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

3.重新启动客户端

重新启动应用程序以加载MCP服务器。

CLI使用情况

直接从命令行生成图像：

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

使用示例

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
     ..."

智能检测

服务器会自动从您的提示中检测最佳设置：

关键字	检测到的类型	纵横比
“比较”、“vs”、“前后”	比较	16:9
“流程”、“过程”、“管道”	流程	16:9
“架构”、“系统”、“层”	架构	4:3
“时间表”、“路线图”、“阶段”	时间表	16:9
“层次结构”、“组织结构图”、“树”	层次结构	4:3
“矩阵”、“网格”、“象限”	矩阵	1:1
“演示文稿”、“幻灯片”、“4k”	（任意）	4k分辨率
“正方形”	（任意）	1:1
“宽”、“横幅”、“页眉”	（任意）	16:9
“肖像”、“手机”、“故事”	（任意）	9:16

样式模式

模式	描述
`professional` （默认）	白色背景，SaaS调色板，无衬线字体，干净的企业外观
`creative`	没有美学限制——您的提示可以控制颜色、字体、背景和艺术效果

“复古”、“漫画”、“黑暗主题”、“水彩”、“复古”和“素描”等关键词会自动触发提示切换到 creative 模式。

支持的模型

型号ID	代号	级别	最适合
`gemini-3-pro-image-preview`	Nano Banana Pro	Pro（默认）	复杂图表，高保真文本渲染，专业资产。使用推理（“思考”）。
`gemini-3.1-flash-image-preview`	Nano Banana 2	Flash	速度、高容量、低延迟用例。支持0.5K–4K分辨率。
`gemini-2.5-flash-image`	Nano Banana	Flash（传统）	最便宜的基本图像生成。

通过设置 VERTEX_AI_IMAGE_MODEL 环境变量。

建筑

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

运作原理

智能分析: analyzePrompt() 对类型关键字进行分数提示，返回置信度
澄清问题：信心低→ 返回问题而不是生成
提示增强：用风格说明（专业或创意）+水印包装提示
技术图表：架构/流类型获得可视化词汇注入（DB的圆柱体、队列的管道等）
图像生成：使用顶点AI模式 @google/genai 软件开发工具包
重试逻辑：3次指数回退尝试（1秒→ 2s → 4s)
图像验证：验证生成的字节（PNG/JPEG/WebP/GIF）、正确的扩展名和尺寸
会话跟踪：每个MCP连接/会话的内存中（适用于集中式服务器）

部署模式

┌──────────────┐     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)     │
└──────────────┘                                            └──────────────────┘

环境变量

变量	默认值	描述
`VERTEX_AI_API_KEY`	-	Vertex AI API键（首选）
`GOOGLE_API_KEY`	--	向后兼容别名
`GOOGLE_CLOUD_API_KEY`	--	向后兼容别名
`VERTEX_AI_IMAGE_MODEL`	`gemini-3-pro-image-preview`	图像生成模型
`MCP_AUTH_MODE`	`token`	身份验证模式： `token`, `oidc`, `none`
`MCP_AUTH_TOKEN`	--	静态承载令牌
`MCP_AUTH_TOKENS`	--	逗号分隔的多个标记
`OIDC_ISSUER`	--	OIDC发卡机构URL（OIDC模式需要）
`OIDC_AUDIENCE`	--	预期的令牌受众
`OIDC_JWKS_URI`	--	覆盖JWKS URI（跳过发现）
`MCP_ALLOW_QUERY_TOKEN`	`1` （令牌模式）	允许 `?token=...` 查询参数身份验证
`MCP_REMOTE_URL`	`http://localhost:3000/mcp`	代理远程URL
`MCP_BEARER_TOKEN`	--	代理身份验证令牌
`HOST`	`0.0.0.0`	HTTP服务器绑定主机
`PORT`	`3000`	HTTP服务器绑定端口
`OUTPUT_DIR`	`./data/out`	生成图像的输出目录
`PUBLIC_BASE_URL`	`http://localhost:$PORT`	下载链接的基本URL
`INLINE_IMAGES`	`0`	在工具响应中包含base64图像数据
`MCP_SESSION_TIMEOUT_MIN`	`30`	会话超时（分钟）
`MCP_MAX_SESSIONS`	`100`	最大并发会话数
`ALLOWED_HOSTS`	--	允许使用逗号分隔的主机头

贡献

欢迎投稿！请在上打开问题或PR GitHub.

许可证

麻省理工学院