@qmediat.io/ideogram-mcp

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) |

Available Tools

| 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