内容
# GPT Image 2 Codex MCP + Skill
一个可复用的本地 MCP 项目，让 Codex 使用 `GPT-5.5` 作为主模型，同时通过本地 `gpt_image` MCP 工具调用 `GPT Image 2` 生成图片。
项目包含：
- 本地 MCP Server：`generate_image` 工具。
- Codex Skill：让 Codex 在用户要求生成图片时自动调用 MCP。
- 安装脚本：自动复制服务、安装依赖、更新 `~/.codex/config.toml`。
- 直连测试脚本：绕过 Codex，直接验证图像接口和密钥。
## 目录结构
```text
gpt-image-2-codex-mcp/
├── src/gpt_image_mcp/server.py # MCP 服务
├── skill/SKILL.md # Codex Skill
├── scripts/install.sh # 一键安装
├── scripts/update_codex_config.py # 写入 Codex MCP 配置
├── scripts/test_direct.py # 直连图像接口测试
├── examples/codex-config.toml # 手动配置示例
└── docs/troubleshooting.md # 常见问题
```
## 快速安装
> 不要把真实 API Key 提交到 Git。建议只通过环境变量传入。
```bash
git clone <your-repo-url> gpt-image-2-codex-mcp
cd gpt-image-2-codex-mcp
export OPENAI_API_KEY="YOUR_IMAGE_API_KEY"
export IMAGE_API_BASE_URL="http://20.246.64.40/v1"
export IMAGE_MODEL="gpt-image-2"
./scripts/install.sh
```
安装脚本不会修改你的 Codex 主模型；主模型继续使用你现有的 `GPT-5.5` 配置。安装完成后，完全重启 Codex App/CLI。
## 如果希望把密钥写入 Codex MCP 专用配置
这种方式更方便，但会把密钥保存在本机 `~/.codex/config.toml` 中。不要提交这个文件。
```bash
export OPENAI_API_KEY="YOUR_IMAGE_API_KEY"
export IMAGE_API_BASE_URL="http://20.246.64.40/v1"
export WRITE_API_KEY_TO_CONFIG=true
./scripts/install.sh
```
## 直连测试接口
安装前或安装后都可以先测试接口是否可用：
```bash
export OPENAI_API_KEY="YOUR_IMAGE_API_KEY"
export IMAGE_API_BASE_URL="http://20.246.64.40/v1"
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python scripts/test_direct.py --output test.png
```
成功后会输出生成图片的绝对路径。
## 在 Codex 中使用
重启 Codex 后，可以直接说：
```text
生成一张 1024x1024 的蓝色科技风 Logo，白色背景，简洁现代。
```
Skill 会要求 Codex 调用：
```text
mcp__gpt_image.generate_image
```
生成后 Codex 会用 `view_image` 查看结果，并告诉你文件绝对路径。
## MCP 工具参数
`generate_image` 支持：
- `prompt`：完整图片描述。
- `size`：例如 `1024x1024`、`1536x1024`、`1024x1536`。
- `quality`：`low`、`medium`、`high` 或 `auto`。`auto` 表示不显式传 `quality`。
- `filename`：可选输出文件名。
默认规则：
- PPT 横版图：`1536x1024`、`high`。
- 正方形 Logo：`1024x1024`、`high`。
## 手动配置
如果不使用安装脚本，可以参考 `examples/codex-config.toml`，把配置加入 `~/.codex/config.toml`。
关键配置：
```toml
[mcp_servers.gpt_image.env]
IMAGE_API_BASE_URL = "http://20.246.64.40/v1"
IMAGE_MODEL = "gpt-image-2"
IMAGE_OUTPUT_DIR = "/Users/you/.codex/generated-images"
IMAGE_API_KEY_ENV = "OPENAI_API_KEY"
```
## 安全建议
- 不要在 README、示例配置或 Git 历史里提交真实密钥。
- 如果密钥曾经在聊天、日志或截图中暴露，建议立即轮换。
- 对外发布仓库前，运行 `git grep -n "sk-"` 检查是否泄露密钥。
## 常见问题
见 `docs/troubleshooting.md`。
