MCP server for the Ideogram V3 API — generate, edit, remix, upscale, and describe images from Claude Code, Claude Desktop, or any MCP client.
Why this server?
- 7 tools — full Ideogram V3 coverage (generate, edit, remix, reframe, replace background, upscale, describe)
- Security-first — SSRF protection, symlink rejection, Content-Type validation, path traversal prevention, Zod response validation (details)
- 2 runtime dependencies —
@modelcontextprotocol/sdk + zod. No axios, no form-data, no HTTP libraries
- Native Ideogram API — direct V3 endpoints, not proxied through fal.ai or Replicate
- Production-hardened — retry with exponential backoff, safety filter handling, partial failure resilience
Quick Start
npm install -g @qmediat.io/ideogram-mcp
Or use directly:
npx @qmediat.io/ideogram-mcp
Requires IDEOGRAM_API_KEY — get one at ideogram.ai/manage-api.
Configuration
Claude Code
Add to ~/.claude.json → mcpServers:
{
"ideogram": {
"command": "npx",
"args": ["-y", "@qmediat.io/ideogram-mcp"],
"env": {
"IDEOGRAM_API_KEY": "your-api-key",
"IDEOGRAM_OUTPUT_DIR": "/tmp/ideogram-output"
}
}
}
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"ideogram": {
"command": "npx",
"args": ["-y", "@qmediat.io/ideogram-mcp"],
"env": {
"IDEOGRAM_API_KEY": "your-api-key",
"IDEOGRAM_OUTPUT_DIR": "/tmp/ideogram-output"
}
}
}
}
Environment Variables
| Variable | Required | Default | Description |
|---|
IDEOGRAM_API_KEY | Yes | — | Your Ideogram API key (get one here) |
IDEOGRAM_OUTPUT_DIR | No | /tmp/ideogram-output | Any folder where you want images saved. Use absolute paths (e.g. /home/user/images/ideogram) |
| Tool | Description | Key Parameters |
|---|
ideogram_generate | Generate images from text prompts | prompt, aspect_ratio, rendering_speed, style_type, num_images |
ideogram_describe | Generate text description of an image | image (file path) |
ideogram_edit | Edit areas of an image with mask-based inpainting | image, mask, prompt |
ideogram_remix | Transform an image with a new prompt | image, prompt, image_weight (0-100) |
ideogram_reframe | Extend an image to a new resolution (outpainting) | image, resolution (69 valid sizes) |
ideogram_replace_background | Replace background, preserving foreground | image, prompt |
ideogram_upscale | Upscale with guided enhancement | image, resemblance (0-100), detail (0-100) |
Common Parameters
| Parameter | Available In | Values |
|---|
rendering_speed | generate, edit, remix, reframe, replace_background | FLASH, TURBO, DEFAULT, QUALITY |
magic_prompt | generate, edit, remix, replace_background, upscale | AUTO, ON, OFF |
style_type | generate, edit, remix | AUTO, GENERAL, REALISTIC, DESIGN, FICTION |
aspect_ratio | generate, remix | 1x1, 16x9, 9x16, 4x3, 3x4, and 10 more |
num_images | all tools | 1-8 |
seed | all tools | 0-2,147,483,647 |
Security
This server is designed with a zero-trust, minimal-dependency approach:
- SSRF protection — HTTPS-only downloads, hostname allowlist, redirect blocking
- Symlink rejection —
lstat() rejects user-created symlinks before reading
- Content-Type validation — downloads must be
image/*, rejecting HTML/JSON error pages
- Zod response validation — API responses parsed through schemas, no blind type casts
- Path traversal prevention — extension allowlist +
path.relative() containment check
Full details in SECURITY.md.
Development
git clone https://github.com/qmediat/ideogram-mcp.git
cd ideogram-mcp
npm install
npm run build
Run locally:
IDEOGRAM_API_KEY=your-key node dist/index.js
Contributing
See CONTRIBUTING.md for architecture guidelines and PR requirements.
License
MIT — Quantum Media Technologies