Content
# 🎨 Image Generation MCP Server
A picture generation MCP server for **Claude Code**. Let Claude generate images based on your descriptions or edit existing images.
## What Can It Do?
- **Text-to-Image** — Say "draw a cyberpunk-style cat" to generate an image
- **Image-to-Image** — Provide a reference image and let the AI modify it according to your requirements (change style, add elements, adjust color, etc.)
- **Automatic Saving** — Generated images are automatically saved to the project folder or desktop
## Example Results
```
You: "Draw a little girl eating an ice cream"
→ ✨ Image generated and saved in the project directory
You: "Change this image to a pencil sketch style"
→ ✨ Image edited successfully! The reference image has been modified according to your requirements
```
## Implementation Principle
```
┌─────────────────────┐ stdio ┌──────────────────────────┐
│ Claude Code Agent │ ◄─── MCP ────► │ image-mcp/server.py │
│ │ │ (FastMCP Python service) │
│ User proposes image generation requirements │ │ │
│ Agent automatically calls tools │ │ Tool: generate_image() │
└─────────────────────┘ └───────────┬──────────────┘
│ HTTP (OpenAI compatible)
▼
┌──────────────────┐
│ Image Generation API │
│ (e.g., gpt-image, │
│ dall-e, flux, etc.) │
└──────────────────┘
```
### Technical Stack
| Component | Technology |
|---|---|
| MCP Framework | [FastMCP](https://github.com/jlowin/fastmcp) (Python) |
| Communication Protocol | MCP stdio (standard input/output) |
| API Protocol | OpenAI compatible format (`/images/generations`) |
| Image Processing | base64 / Pillow |
| Configuration Storage | `~/.claude/mcp-image-gen-config.json` |
### Tool Interface
MCP exposes a tool `generate_image` with the following parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | ✅ | Image description or editing requirements |
| `image_path` | string | ❌ | Reference image path (pass this parameter for image-to-image mode) |
| `output_dir` | string | ❌ | Output directory (default is the current working directory) |
| `size` | string | ❌ | Image size, e.g., `1024x1024` (default) |
## Quick Start
### 1. Install Dependencies
```bash
pip install fastmcp httpx
```
### 2. Configure API Credentials
Run the configuration script:
```bash
cd image-mcp
python setup_config.py
```
Enter the following information when prompted:
- **API Address** (base_url) — Your image generation API address
- **API Key** — Your API key
- **Model Name** — e.g., `gpt-image-2-03`, `dall-e-3`, `flux-pro`, etc.
The configuration script will also ask if you want to register with Claude Code.
### 3. Use in Claude Code
After configuration, directly tell Claude:
```
Draw a cute little cat
Generate a cyberpunk-style city night scene image, 1920x1080
Change this image to a watercolor style
```
Claude Code will automatically call the MCP tool to generate images. The generated images will be saved in your current project directory (or desktop if it's a global conversation).
### Manual Registration with Claude Code
If you don't want to use the configuration script, you can manually add the following to `~/.claude/settings.json`:
```json
{
"mcpServers": {
"image-generator": {
"command": "python",
"args": ["/path/to/image-mcp/server.py"]
}
}
}
```
Restart Claude Code or execute `/reload` after adding.
### Using Environment Variables (more secure)
Set environment variables in `"env"` in `~/.claude/settings.json` (higher priority than configuration files):
```json
{
"mcpServers": {
"image-generator": {
"command": "python",
"args": ["/path/to/image-mcp/server.py"]
}
},
"env": {
"MCP_IMAGE_GEN_API_KEY": "Your API Key",
"MCP_IMAGE_GEN_BASE_URL": "https://api.openai.com/v1",
"MCP_IMAGE_GEN_MODEL": "gpt-image-2-03"
}
}
```
## Security Notes
- **API Key not stored in project folders** — Credentials stored in your `~/.claude/` directory
- Supports two configuration methods: independent configuration files and environment variables (environment variables have higher priority)
- `.gitignore` automatically excludes image files and `__pycache__`
- Sharing the project will not leak any of your credentials
## Project Structure
```
image-mcp/
├── server.py # MCP server main program
├── setup_config.py # Configuration installation script
├── mcp-image-gen-config.example.json # Configuration template (for reference)
├── .gitignore # Git ignore rules
└── README.md # This file
```
## License
MIT
