Content
# GPT Image 2 Codex MCP + Skill
A reusable local MCP project that uses `GPT-5.5` as the main model and calls `GPT Image 2` to generate images through the local `gpt_image` MCP tool.
The project includes:
- Local MCP Server: `generate_image` tool.
- Codex Skill: Automatically calls MCP when the user requests to generate an image.
- Installation script: Automatically copies the service, installs dependencies, and updates `~/.codex/config.toml`.
- Direct connection test script: Bypasses Codex and directly verifies the image interface and key.
## Directory Structure
```text
gpt-image-2-codex-mcp/
├── src/gpt_image_mcp/server.py # MCP Service
├── skill/SKILL.md # Codex Skill
├── scripts/install.sh # One-click installation
├── scripts/update_codex_config.py # Write Codex MCP configuration
├── scripts/test_direct.py # Direct connection image interface test
├── examples/codex-config.toml # Manual configuration example
└── docs/troubleshooting.md # Frequently Asked Questions
```
## Quick Installation
> Do not submit real API Keys to Git. It is recommended to pass them only through environment variables.
```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
```
The installation script will not modify your Codex main model; the main model will continue to use your existing `GPT-5.5` configuration. After installation, completely restart the Codex App/CLI.
## Writing Key to Codex MCP Special Configuration
This method is more convenient but will save the key in the local `~/.codex/config.toml`. Do not submit this file.
```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
```
## Direct Connection Test Interface
You can test the interface availability before or after installation:
```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
```
After success, it will output the absolute path of the generated image.
## Using in Codex
After restarting Codex, you can directly say:
```text
Generate a 1024x1024 blue tech logo with a white background, simple and modern.
```
The Skill will request Codex to call:
```text
mcp__gpt_image.generate_image
```
After generation, Codex will use `view_image` to view the result and tell you the file's absolute path.
## MCP Tool Parameters
`generate_image` supports:
- `prompt`: Complete image description.
- `size`: For example, `1024x1024`, `1536x1024`, `1024x1536`.
- `quality`: `low`, `medium`, `high`, or `auto`. `auto` means not explicitly passing `quality`.
- `filename`: Optional output filename.
Default rules:
- PPT horizontal map: `1536x1024`, `high`.
- Square logo: `1024x1024`, `high`.
## Manual Configuration
If you do not use the installation script, you can refer to `examples/codex-config.toml` and add the configuration to `~/.codex/config.toml`.
Key configuration:
```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"
```
## Security Recommendations
- Do not submit real keys in README, example configurations, or Git history.
- If the key has been exposed in chat, logs, or screenshots, it is recommended to rotate it immediately.
- Before releasing the repository, run `git grep -n "sk-"` to check if the key is leaked.
## Frequently Asked Questions
See `docs/troubleshooting.md`.
