Image2

MCP Server for the company image2 text-to-image API. Allows Claude Code, Codex, and other MCP-compatible AI tools to generate images directly.

🚀 Quick Start

自动安装（推荐）

git clone <repo-url>
cd image2-mcp
bash scripts/setup.sh

脚本会自动完成：

1. 检查/安装 uv
2. 安装 Python 依赖（uv sync）
3. 引导你输入 API Key（或从 ~/.claude/.env 复用已有 key）
4. 写入 ~/.claude/.env 环境配置
5. 将 image2 注册到 ~/.claude.json（Claude Code 的 MCP 配置）
6. 运行健康检查验证一切正常

完成后重启 Claude Code，说「帮我生成一张图片」即可。

手动安装

# 1. 安装依赖
uv sync

# 2. 配置环境变量
cp .env.example ~/.claude/.env
# 编辑 ~/.claude/.env，将 MAGENE_API_KEY 改为你的真实 key：
#   MAGENE_API_KEY=user_xxxxxxxx

# 3. 健康检查
uv run python -m image2_mcp --health-check

MCP 配置需要手动添加到 ~/.claude.json 的顶层 mcpServers 字段：

{
  "mcpServers": {
    "image2": {
      "command": "bash",
      "args": [
        "-c",
        "set -a; [ -f ~/.claude/.env ] && . ~/.claude/.env; [ -f .env ] && . ./.env; set +a; exec /Users/你的用户名/.local/bin/uv run --directory /path/to/image2-mcp python -m image2_mcp"
      ],
      "env": {
        "PATH": "/Users/你的用户名/.local/bin:/usr/local/bin:/usr/bin:/bin",
        "HOME": "/Users/你的用户名"
      },
      "description": "文生图 — 调用公司统一 API 平台 image2 模型生成图片",
      "type": "stdio"
    }
  }
}

⚠️ 注意将 /Users/你的用户名/ 替换为实际路径。uv 的路径可通过 which uv 获取。

---

⚙️ 环境变量

变量	必填	默认值	说明
MAGENE_API_KEY	是	—	公司 API 平台的 key
MAGENE_API_BASE_URL	否	http://tops.magene.cn:11636/api/v1/images/generations	API 地址
IMAGE2_OUTPUT_DIR	否	自动检测（项目 /output）	图片保存路径
IMAGE2_MODEL	否	openai/gpt-image-2	模型名称

图片输出目录的优先级：

1. 显式参数
2. IMAGE2_OUTPUT_DIR 环境变量
3. CLAUDE_PROJECT_DIR → <项目>/output/（Claude Code 自动设）
4. IMAGE2_PROJECT_DIR → <项目>/output/（legacy）
5. 当前工作目录 /output
6. 系统临时目录 /image2-output

💡 通常无需手动设置任何目录变量——如果你在某个项目中用 Claude Code 打开，图片会自动存到那个项目的 output/ 文件夹。

---

📐 工具参数

参数	类型	必填	默认值	说明
prompt	string	是	—	图片描述（最长 32000 字符）
size	string	是	—	尺寸，见下方
quality	string	否	auto	low / medium / high / auto
filename	string	否	自动生成	自定义文件名（不含 .png）

可用尺寸：

值	分辨率
1024x1024	1K 方形
1536x1024	1.5K 横版
1024x1536	1.5K 竖版
2048x2048	2K 方形
2048x1152	2K 横版
3840x2160	4K 横版
2160x3840	4K 竖版
auto	自动

自定义尺寸：WxH 格式，每边 ≤ 3840px，16 的倍数，宽高比 ≤ 3:1，总像素 655,360–8,294,400。

---

🧪 开发

uv sync --group dev
uv run pytest --cov=src --cov-report=term-missing

---

🔧 工作原理

AI: generate_image(prompt="a cat in a garden", size="1024x1024")
    → 服务端校验参数
    → POST 到公司 API
    → 解码 Base64 响应
    → 写入 PNG 到磁盘
    → 返回图片 + 路径 + 用量统计

生成是异步的——AI 调用后立即返回，图片就绪后会通过日志通知。多张图片可并行生成。