@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

Terminal

npm install -g @qmediat.io/ideogram-mcp

Or use directly:

Terminal

npx @qmediat.io/ideogram-mcp

Requires IDEOGRAM_API_KEY — get one at ideogram.ai/manage-api.

Configuration

Claude Code

Add to ~/.claude.json → mcpServers:

config.json

{
  "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:

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

bash

git clone https://github.com/qmediat/ideogram-mcp.git
cd ideogram-mcp
npm install
npm run build

Run locally:

bash

IDEOGRAM_API_KEY=your-key node dist/index.js

Contributing

See CONTRIBUTING.md for architecture guidelines and PR requirements.

License

MIT — Quantum Media Technologies