使用说明
双子座图像生成MCP服务器
一个经过令牌优化的MCP服务器，它通过返回文件路径而非base64数据，使MCP客户端能够实现Gemini图像生成。
为何存在这一现象
现有的Gemini图像生成MCP服务器在Claude代码中出现故障 MCP tool response exceeded token limit 错误。它们返回的是Base64编码的图像数据（每张图像约2.4M个标记），这超出了Claude Code的25,000个标记限制。
这个实现解决了问题 通过将图像保存到磁盘并仅返回文件路径（约20个标记）——a 减少120,000倍 在代币使用方面。
| 实施 | 响应 | 代币 | 结果 |
|---|---|---|---|
| 现有服务器 | Base64 数据 | 2.4M | ❌ 错误 |
| 此服务器 | 文件路径 | ~20 | ✅ 正常工作 |
特点/功能
- **优化后的代币（或标记）**仅返回文件路径（约20个标记，对比240万个）
- 两种生成模式文本到图像和图像到图像的转换
- 兼容的Claude编码在25,000个标记的限制内工作
- ISO 8601 UTC时间戳全球可排序的文件名（
YYYYMMDDTHHMMSSZ.png） - 轻便的最小化依赖
- 快速紫外线供电初创公司
- 简单无需构建步骤
要求
- Python 3.10及以上版本
- 紫外线 - 现代Python包管理器（比pip快10-100倍）
- Gemini API密钥 来自 Google AI Studio（谷歌人工智能工作室）
安装 uv
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Homebrew
brew install uv
# Verify installation
uv --version
快速入门
# 1. Clone and navigate
git clone https://github.com/couhie/mcp-gemini-imggen.git
cd mcp-gemini-imggen
# 2. Configure settings
cp .env.example .env
# Edit .env and set:
# GEMINI_API_KEY - Your API key from Google AI Studio
# OUTPUT_DIR - Directory for generated images (e.g., ~/Pictures/ai)
# Directory will be created automatically if it doesn't exist
# 3. Add to Claude Code
claude mcp add -s user gemini-imggen uv -- --directory $(pwd) run mcp-gemini-imggen
配置
Claude 命令行接口（CLI）（推荐）
claude mcp add -s user gemini-imggen uv -- --directory /absolute/path/to/mcp-gemini-imggen run mcp-gemini-imggen
手动设置
添加到 ~/.claude.json：
{
"mcpServers": {
"gemini-imggen": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mcp-gemini-imggen",
"run",
"mcp-gemini-imggen"
],
"env": {}
}
}
}
注使用绝对路径，而不是（相对路径） ~ （例如。， /Users/yourname/dev/mcp-gemini-imggen)
使用方法/用途
配置完成后，在Claude Code中使用MCP工具：
文本到图像生成
Generate a flat design style cute cat illustration
图像到图像的转换
Transform /Users/name/Pictures/ai/20251015T120000Z.png: make the background blue
注您必须提供现有图像的文件路径。常见使用场景：
- 修改之前生成的图像
- 转换已保存在系统上的图像
- 链式转换：生成 → 转换 → 再次转换
服务器将：
- 使用Gemini 2.5 Flash生成/转换图像
- 将其保存到
$OUTPUT_DIR/YYYYMMDDTHHMMSSZ.png(ISO 8601 通用协调时格式) - 仅返回文件路径（约20个标记）
Claude Code 将自动显示生成的图像。
技术细节
代币优化
Base64编码的响应导致令牌爆炸：
- 1536×1536 PNG 约 1.4MB → Base64 约 1.9MB（增加 33% 的开销）
- 令牌转换：1.9MB ÷ 4个字符/令牌 ≈ 475,000个令牌
- 多张图像（4张）：约1,900,000个标记
- JSON封装器：+500,000个标记
- 总计：约2,400,000个代币 （超过25,000的限制）
解决方案返回文件路径，而非数据
# ❌ Existing: 2.4M tokens
{"type": "image", "data": "iVBORw0KGgo...", "mimeType": "image/png"}
# ✅ This server: ~20 tokens
[{"type": "text", "text": "/Users/name/Pictures/ai/20251015T120000Z.png"}]
故障排除
"uv: command not found" 翻译成中文是：“uv：命令未找到”
首先安装uv：
curl -LsSf https://astral.sh/uv/install.sh | sh
“GEMINI_API_KEY”环境变量是必需的
从以下位置获取您的API密钥 Google AI Studio（谷歌人工智能工作室） 并添加到 .env
“需要设置 OUTPUT_DIR 环境变量”
设置您所需的输出目录 .env （例如。， OUTPUT_DIR=~/Pictures/ai）。 如果目录不存在，将会自动创建。
图像未生成
- 验证API密钥是否有效，有效期至 Google AI Studio（谷歌人工智能工作室）
- 检查API配额限制
- 验证OUTPUT_DIR路径是否有效（父目录必须可写）
做出贡献
欢迎贡献！请提交一个拉取请求。
许可证
MIT 许可证 - 请参阅 许可证 详情请见。
