qmediat 发布 ideogram-mcp：一个 MCP server 接入 Ideogram 全系图像模型

MCP server for the Ideogram platform through its v2 API: every image model Ideogram sells through one API key — Ideogram 4.5, 4.0, 3.0, 2a and 2.0, GPT Image, Nano Banana, P-Image, Z-Image, the Topaz upscalers — for generate, inpaint, remix, reframe, replace background, upscale and describe, from Claude Code, Claude Desktop or any MCP client over stdio. Every call can be priced first (the API's own dry run), long jobs are returned by id and collected later, and any other operation the release serves is one validated raw call away. Built from Ideogram's OpenAPI specification (ADR-0001).

Why this server?

• The platform, not one model — model on every tool, with each model's own fields (a field the model does not take is refused, naming the models that do). The model lists and fields come from Ideogram's specification, so a new model is a reviewed snapshot update, not a rewrite
• Price before you pay — ideogram_quote asks the API what exactly this call would cost (USD and credits; nothing generated or billed)
• Never billed twice — a job is returned the moment Ideogram accepts it; the tool waits up to wait_s and otherwise hands back the generation_id for ideogram_generation. A request is resent only when it never left the machine or got a 429
• Everything else, validated — ideogram_operations lists what the API offers; ideogram_api calls any served operation by id, checked against its own schema first
• Guarded I/O — per-operation upload limits checked before any file is read, streamed downloads with a 50 MB cap from allow-listed HTTPS hosts, typed 402/429 errors that say what to do (details)
• 2 runtime dependencies — @modelcontextprotocol/sdk + zod; native fetch

Quick Start

Requires Node.js 22 or newer and an IDEOGRAM_API_KEY — create one in Ideogram's API dashboard at ideogram.ai/platform → API Keys → Create key (setup guide).

claude mcp add --scope user ideogram -e IDEOGRAM_API_KEY=your-api-key -e IDEOGRAM_OUTPUT_DIR=/tmp/ideogram-output -- npx -y @qmediat.io/ideogram-mcp

or by hand (below). npm install -g @qmediat.io/ideogram-mcp installs the ideogram-mcp command, which can replace the npx line in any config.

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

Available Tools

Each model's fields are listed in the tool's schema (one variant per model) and in docs/API-REFERENCE.md, generated from the specification. Image inputs are local file paths (or Ideogram asset identifiers where a model takes them); each operation's own upload limits apply, checked each file against its field's limit before any is read, the whole encoded request against the request cap before it is sent.

Waiting, and collecting later

A generation is sent asynchronously and returned the moment Ideogram accepts it. The tool then waits up to wait_s seconds (default 45, at most 50: MCP clients time a call out at 60 s), polling at 2 s, ×1.5, up to 30 s apart. A job still running at the end of the wait comes back as its generation_id: ideogram_generation {"generation_id": "…"} collects it later, in this session or another. Sending the request again would start — and bill — a second job. Every tool call has one budget, fixed when it starts: 55 s (the caller's 60 s minus a margin), ended earlier by the caller's own cancellation (a client that times out or a user who cancels). Every request, retry sleep (Retry-After included), poll and download of the call is judged against what remains of it, so nothing of a call outlives its caller and a request that creates work is never resent after the caller has given up: a POST is resent only when the time left also covers an attempt as long as the one just rejected. A download the budget cuts is listed as not saved beside the generation id; ideogram_generation saves it in a new call. What that leaves open: an upload that needs more than 55 s cannot be served inside one MCP call at all; a request the budget cuts while it is in flight is reported as possibly accepted (never resent); and a job the API accepts after the caller gave up keeps an id nobody receives — a limit of the 60 s client, not of this server.

Prices

ideogram_quote sends exactly the request the tool would send, with Ideogram's dry_run: the answer is the price in USD and credits (at your account's credit rate), exact or an estimate with its upper bound; nothing is generated, stored or billed. Describe has no dry run, so it cannot be quoted. A completed generation shows the cost Ideogram reports for it. This server keeps no price table: prices are the API's, per request.

Compatibility with 1.x

Calls written for 1.x keep working through 2.x, and the result says what was mapped:

A 1.x field that the chosen v2 model does not take is refused with the models that take it (the changelog has the full table).

The raw call

ideogram_api runs any operation this release serves — the curated ones and every other /v2/image operation (precise edit, remove background, remove object) — by its id, with its parameters kept in their places: {"operation": "…", "params": {"path": {}, "query": {}, "body": {}}, "files": [{"field": "image", "path": "…"}], "dry_run": false}. The parameters are checked against the operation's own schema and rules before anything is sent. Operations Ideogram's documentation does not list need allow_undocumented: true; web-app (Bearer) and internal operations are refused; video, the commercial tools and account usage come in later releases (plan).

Security

A defensive, minimal-dependency design:

• SSRF protection — downloads over HTTPS only, from allow-listed hosts, redirects blocked
• Symlink rejection — lstat() rejects a symlinked input file before reading (a symlinked parent directory is resolved)
• Upload limits per operation — each file checked with stat() against its field's limit before any is read; the local file name is never sent (a file goes as <field>.<ext>)
• Streamed, capped downloads — written to disk with a byte counter, stopped at 50 MB, the partial file removed; image/* or video/mp4 required
• Schema validation — inputs against each model's generated schema before any request; a success response the specification's schema rejects is reported as a contract mismatch, never as a success
• Input paths — the model may name any readable image file on the machine for upload; run the server as a user whose readable images you are willing to send to Ideogram

Full details in SECURITY.md.

Development

git clone https://github.com/qmediat/ideogram-mcp.git
cd ideogram-mcp
npm install
npm run build
npm run typecheck
npm test            # builds, then every test against a fake API (no key, no network); with IDEOGRAM_API_KEY set, the live dry-run suite runs too (below)

The specification snapshot drives the code: npm ci --prefix scripts/spec-gen && npm run spec:generate regenerates src/generated/ (CI checks it with npm run spec:check), npm run docs:api the API reference, npm run spec:pull compares the live specification with the snapshot. These scripts need Node.js 22.18 or newer (type stripping). With IDEOGRAM_API_KEY set, test/live-dry-run.test.mjs quotes every curated model at no cost and writes the prices to docs/PRICES-<date>.md.

Run locally:

IDEOGRAM_API_KEY=your-key node dist/index.js

Contributing

See CONTRIBUTING.md for architecture guidelines and PR requirements.

Trademarks and affiliation

Ideogram is a trademark of Ideogram. This is an independent, community-maintained integration published by Quantum Media Technologies sp. z o.o.; it is not affiliated with, sponsored by or endorsed by Ideogram. Use of the Ideogram API through this server is subject to Ideogram's own terms and to your own API key or account.

License

MIT — Quantum Media Technologies

Made by Quantum Media Technologies · more open source from qmediat