# ideogram-mcp [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/qmediat/ideogram-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1504  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ideogram-mcp

## Description
Ideogram V3 API — generate, edit, remix, reframe, replace background, upscale images

## Tools
Capabilities this server exposes over MCP:

- **ideogram_generate** — Create images from a text prompt with any image model Ideogram's API sells: Ideogram 4.5, 4.0 and 3.0 (with transparent, character and custom-model variants), 2a and 2.0, GPT Image, Nano Banana, P-Image, Z-Image, or auto. Each model takes its own fields (one variant per model in this schema). Default model: ideogram-3. Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).
- **ideogram_precise_edit** — Edit an image with Ideogram 4.5 at its exact size: pixels the edit does not change stay as they are. Takes the image, an optional mask (black = edit), up to 4 reference images that guide the edit, and context_window to confine it. Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).
- **ideogram_inpaint** — Repaint the masked part of an image (black in the mask = repaint) with Ideogram 3.0 or its character / custom-model variants. Needs the source and the mask, each a local file, a public https URL or an Ideogram asset. Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).
- **ideogram_remix** — Make new images from a source image and a prompt (Ideogram 3.0 and its variants, Ideogram 4.0, or auto); image_weight sets how closely the result follows the source. Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).
- **ideogram_reframe** — Extend an image to a new size by outpainting (Ideogram 3.0 or Nano Banana 2). Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).
- **ideogram_replace_background** — Replace the background of an image and keep its subject (Ideogram 3.0 or GPT Image 2); the prompt describes the new background. Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).
- **ideogram_remove_background** — Remove the background of an image: the foreground comes back as a transparent PNG. Takes a local file, a public https URL or an Ideogram asset. Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).
- **ideogram_remove_object** — Remove a masked object from an image (white in the mask = remove) and fill the gap. Needs the source and a mask of the same size, each a local file, a public https URL or an Ideogram asset. Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).
- **ideogram_upscale** — Enlarge an image (auto, Topaz Bloom, Redefine, Standard, Text Refine and Wonder, or Nano Banana Pro); each model takes its own controls. Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).
- **ideogram_describe** — Describe an image in words (Ideogram 3.0) or as a structured JSON prompt (Ideogram 4.0). Takes a local file, a public https URL or an Ideogram asset. Describe has no price quote (the API offers no dry run for it).
- **ideogram_video_text** — A video from a text prompt (Seedance 2.5 by default, Seedance 2, Kling 3 Standard, MiniMax H3); each model takes its own duration, aspect ratio, resolution and audio controls. Saved as mp4 to the output directory (never inline); long jobs come back as a generation_id for ideogram_generation. Give duration to know the price: omitted, Seedance is quoted at its maximum length. ideogram_quote prices a call first.
- **ideogram_video_image** — A video that starts from an image (and optionally ends on another): Seedance 2.5 by default, Seedance 2, Kling 3 Standard, MiniMax H3. Takes local files, public https URLs or Ideogram assets. Saved as mp4; long jobs come back as a generation_id. ideogram_quote prices a call first.
- **ideogram_video_reference** — A video guided by reference images, audio clips (MP3/WAV: 2-30 s on Seedance 2.5, 2-15 s on Seedance 2 and MiniMax) and videos stored with Ideogram, in prompt order: Seedance 2.5 by default, Seedance 2, MiniMax H3; at least one reference image or video. Saved as mp4; long jobs come back as a generation_id. ideogram_quote prices a call first.
- **ideogram_layerize** — Turn a flat image into an editable design (Ideogram 3.0): the detected text comes back as positioned text blocks with matched fonts, sizes and colours, beside a text-free base image that is saved. Optional font files to match against; ideogram_quote prices a call first.
- **ideogram_ad_localizer** — Translate an ad's copy into one target language (one request per language; Arabic right-to-left), keeping its layout, logos, brand type and product; exact_copy pins pre-approved wordings line by line. Takes the ad as a local file, a public https URL or an Ideogram asset. Results are saved to the output directory; long jobs come back as a generation_id for ideogram_generation; ideogram_quote prices a call first.
- **ideogram_ad_resizer** — Reframe an ad to a platform's exact ad size (resolution WIDTHxHEIGHT from the list; platform picks the published safe zone), optionally editing while reframing. Takes the creative as a local file, a public https URL or an Ideogram asset. Results are saved to the output directory; long jobs come back as a generation_id for ideogram_generation; ideogram_quote prices a call first.
- **ideogram_ad_variations** — Vary an ad along one axis — people, setting, group_size or scene — keeping its aspect ratio and product. Takes the creative as a local file, a public https URL or an Ideogram asset. Results are saved to the output directory; long jobs come back as a generation_id for ideogram_generation; no price quote (the operation offers no dry run).
- **ideogram_colorways** — Recolor a product photo: up to 4 masks, each paired by position with a six-digit hex colour; everything outside the masks is preserved. Takes the photo and the masks as local files, public https URLs or Ideogram assets. Results are saved to the output directory; long jobs come back as a generation_id for ideogram_generation; ideogram_quote prices a call first.
- **ideogram_ghost_mannequin** — A garment on an invisible mannequin from its photos (front, back, left, right, top, bottom and more angles, as files, URLs or assets), in the view asked (front, three_quarter, back), on a clean white studio background; instruction and metadata add factual product context. Results are saved to the output directory; long jobs come back as a generation_id for ideogram_generation; ideogram_quote prices a call first.
- **ideogram_material_swap** — Apply the material of reference images — colour, texture, pattern scale, orientation — to the masked regions of a product photo (up to 4 masks and materials, paired by position). Files, public https URLs or Ideogram assets. Results are saved to the output directory; long jobs come back as a generation_id for ideogram_generation; ideogram_quote prices a call first.
- **ideogram_model_pose_variants** — Re-pose the model of a fashion image by a plain-language pose or camera instruction (an optional pose reference asset). The source as a local file, a public https URL or an Ideogram asset. Results are saved to the output directory; long jobs come back as a generation_id for ideogram_generation; no price quote (the operation offers no dry run).
- **ideogram_sketch_to_render** — Render a fashion sketch as a product photo, with material and rendering direction and the construction details the sketch does not show. The sketch as a local file, a public https URL or an Ideogram asset. Results are saved to the output directory; long jobs come back as a generation_id for ideogram_generation; no price quote (the operation offers no dry run).
- **ideogram_magic_prompt** — Rewrite a natural-language prompt into an Ideogram 4.0 structured JSON prompt (and the aspect ratio the model picks for it, or the one you pin). Nothing is generated; no price quote (the v1 operation offers no dry run).
- **ideogram_layerize_logos** — Detect reference logos and image elements in a flat design and remove them: the text-free base image is saved, the detected layers come back with the reference each matched (REF_0, REF_1, … in the order given). The design and the references as local files or public https URLs. No price quote (the v1 operation offers no dry run).
- **ideogram_provenance** — Check whether an image was created by Ideogram: the provenance record (provider, system version, generation id, creation time, validation state) as Ideogram answers it. The image as a local file or a public https URL. Free of charge; no price quote.
- **ideogram_snap_mask** — Snap a hand-drawn binary mask to the object it marks: the snapped mask comes back as a PNG (white = the object), saved to the output directory. Use it as is for ideogram_remove_object (white = the region to remove) and for the colorways and material swap masks (white = the region to change); invert it for ideogram_inpaint, whose mask takes black as the region to repaint. The image and the mask as local files or public https URLs. No price quote (the v1 operation offers no dry run).
- **ideogram_edit** — Deprecated alias of ideogram_inpaint, kept through 2.x for 1.x callers: the same arguments and models (see ideogram_inpaint's schema).
- **ideogram_quote** — Ask Ideogram what a call would cost before making it: give the curated tool's name and the arguments you would pass it. Answers USD and credits from the API's own dry run (exact, or an estimate with its upper bound). Nothing is generated or billed.
- **ideogram_generation** — Collect the result of a generation by its generation_id (from a tool that answered 'still running', or from an earlier session): waits up to wait_s for it, then saves its images or videos. Reading a generation is free and never runs it again.
- **ideogram_usage** — Your organization's billed API usage as Ideogram reports it: dense time buckets of line items (product, endpoint, cost, units, the redacted API key), summed per product, unit and currency here, the buckets written unchanged to a file in the output directory (the shape ai-cost reads; printed too when small). Default: the last 7 days by day. Needs an API key whose owner is an organization admin. Reads only.
- **ideogram_invoices** — Your organization's invoices with their line items — the billing record the usage reconciles against. Needs an API key whose owner is an organization admin. Reads only.
- **ideogram_api_keys** — The API keys in your organization, newest first, key material redacted (the id and the redacted prefix match the usage report's line items). Needs an API key whose owner is an organization admin. Reads only.
- **ideogram_datasets** — Your training datasets: the list (optionally searched by name), or one dataset by id with its files, captions and the models trained from it. Reads only.
- **ideogram_dataset_upload** — Upload images (JPEG, PNG, WebP), caption sidecars (.txt/.json named like their image) and .zip archives into a dataset — an existing one by dataset_id, or a new one created from name — from local paths or public https URLs. Answers what was accepted and what failed and why.
- **ideogram_train** — Start training a custom Ideogram 4.0 (default) or 3.0 model from a dataset of 15-100 images; a hyperparameter routes to the advanced operation. Returns the model id to follow with ideogram_models; a completed model's custom_model_uri generates through ideogram_generate.
- **ideogram_models** — Your custom models and those shared with your organization: the list (by scope and status), or one by id with its training runs. Reads only.
- **ideogram_operations** — Discover what Ideogram's API offers and what this server serves: no input = every family; family = its operations (model, class, support, quotable); operation = its fields, file limits and rules, ready for ideogram_api.
- **ideogram_api** — Advanced: call an Ideogram operation by id (from ideogram_operations) when no curated tool covers it — a model the documentation index does not list (allow_undocumented), or a call with webhook_url / target_collection_id. params holds path, query, headers and body apart; files maps local files or public https URLs to file fields. Checked against the operation's own schema before anything is sent; dry_run prices it instead.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ideogram-mcp": {
    "command": "npx",
    "args": ["-y","@qmediat.io/ideogram-mcp"],
    "env": {
      "IDEOGRAM_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `IDEOGRAM_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What ideogram-mcp MCP server does

The ideogram-mcp MCP server exposes Ideogram’s image and video capabilities through the Model Context Protocol. It supports text-to-image generation, image editing, remixing, outpainting, background replacement or removal, object removal, upscaling, image description, and several fashion and advertising workflows.

Video tools can create clips from text, a start image, an optional end image, or reference media. Other tools can convert a flat design into a text-free base image plus detected text blocks, recolor masked product areas, swap materials, generate pose variants, or render a fashion sketch as a product image.

The server also includes utility operations for prompt restructuring, logo detection, provenance checks, mask snapping, price quotes, generation retrieval, and reported usage. This places the project in the Multimedia Process category for agent workflows that need both media creation and post-processing.

## How it works

Each MCP tool maps to an Ideogram API operation and accepts model-specific fields. The curated tools validate the selected model and reject fields that the model does not support. Inputs may include prompts, masks, reference images, URLs, local files, audio clips, and videos, depending on the operation.

Long-running requests return a generation ID after Ideogram accepts the job. The server waits for a configured period when possible; if the job is not finished, call `ideogram_generation` with that ID to collect the resulting images or video. Generated files are saved locally, including video output as MP4.

`ideogram_quote` can request the API’s price for a call before generation, returning the reported USD and credit amounts without creating or billing a result. `ideogram_usage` reports billed usage by product and currency, with a default seven-day daily view.

## Setup and configuration

The ideogram-mcp MCP server requires Node.js 22 or newer and an Ideogram API key created in the Ideogram API dashboard. Install it on demand with `npx -y @qmediat.io/ideogram-mcp`, or install the package globally to use its `ideogram-mcp` command.

For Claude Code or Claude Desktop, configure a stdio MCP entry with the package command and these environment variables:

- `IDEOGRAM_API_KEY` — required API credential.
- `IDEOGRAM_OUTPUT_DIR` — optional absolute directory for saved images and other output; the default is `/tmp/ideogram-output`.

The README provides configuration examples for both Claude Code and Claude Desktop. Other MCP clients can launch the same stdio command with the environment variables set.

## Tools and capabilities

The ideogram-mcp MCP server includes tools for:

- Creating, editing, remixing, reframing, inpainting, upscaling, and describing images.
- Removing or replacing backgrounds and removing masked objects.
- Producing text-to-video, image-to-video, and reference-guided video.
- Layerizing designs and optionally matching supplied font files.
- Localizing, resizing, and varying advertisements.
- Applying colorways, material swaps, ghost-mannequin effects, model pose changes, and sketch-to-render workflows.
- Rewriting prompts into Ideogram 4 structured JSON without generating an image.
- Detecting logos, checking Ideogram provenance, and snapping hand-drawn masks to objects.
- Quoting prices, collecting generations, and inspecting reported usage.

## Limitations and notes

Model availability and accepted parameters vary by tool. Masks also use operation-specific conventions: black marks edited or repainted areas for precise editing and inpainting, while white marks objects for removal. Reference-guided video requires at least one reference image or video, and audio duration limits vary by model.

The server checks upload limits before reading files and caps streamed downloads at 50 MB for general media and 512 MB for video. Downloads are restricted to allow-listed HTTPS hosts. A request is retried only when it did not leave the machine or when the API returned a rate-limit response, helping avoid duplicate billing. Privacy defaults and output behavior can vary by model and operation.

_Full upstream README: https://allmcps.com/mcp/ideogram-mcp/readme_