ideogram-mcp

@qmediat.io/ideogram-mcp

通过 v2 API 为 Ideogram 平台提供的 MCP 服务：只需一个 API 密钥，即可使用 Ideogram 售卖的所有图像和视频模型——Ideogram 4.5、4.0、3.0、2a 和 2.0、GPT Image、Nano Banana、P-Image、Z-Image、Topaz 升级工具；用于视频的 Seedance 2.5 和 2、Kling 3、MiniMax H3——支持生成、精准编辑、局部重绘、混搭、重构画幅、更换背景、移除背景、移除对象、升级分辨率、描述、分层和视频生成（通过提示词、图像或参考素材），商业工具（广告本地化、调整尺寸和变体、配色方案、幽灵模特、材质替换、模特姿势变体、草图转渲染），实用工具（魔法提示词、Logo 分层、来源溯源、快照蒙版），以及账户用量、发票和密钥与自定义模型训练；可通过 stdio 从 Claude Code、Claude Desktop 或任何 MCP 客户端调用。每次调用都可以先获取价格（使用 API 自带的试运行功能），长时间运行的任务会返回 ID，稍后可再获取结果；该版本提供的任何其他操作，也都可通过一次经过验证的原始调用完成。基于 Ideogram 的 OpenAPI 规范构建（ADR-0001）。

为什么选择此服务？

• 不只支持单一模型，而是整个系列 — 每个工具都支持 model，并提供各模型专属字段（如果模型不接受某字段，系统会拒绝并指出哪些模型支持该字段）。模型列表和字段均来自 Ideogram 规范，因此新增模型只需更新经过审核的快照，无需重写代码
• 先报价，再付费 — ideogram_quote 会向 API 查询此次调用的确切费用（美元和额度；不会生成内容，也不会扣费）
• 默认保持私密 — 对于支持 private 的精选工具，除非你另行设置，否则都会将其设为 true（对于移除背景、更换背景和 auto 模型，API 自身的默认值是你的套餐设置）；不支持此字段的模型（使用 Ideogram 3.0 重构画幅、移除对象）遵循 API 自身的行为，而 ideogram_api 则会发送你提供的内容
• 绝不重复扣费 — Ideogram 一旦接受任务，就会立即返回任务；工具会等待最多 wait_s，否则会返回 generation_id，供 ideogram_generation 使用。只有在请求未离开本机或收到 429 时，才会重新发送请求
• 其他操作也一律经过验证 — ideogram_operations 会列出 API 提供的操作；ideogram_api 可按 ID 调用任何已提供的操作，并先根据其自身架构进行检查
• 受保护的 I/O — 在读取任何文件之前检查各操作的上传限制；从允许列表中的 HTTPS 主机流式下载，并将大小限制为 50 MB（视频为 512 MB）；提供清晰说明后续操作的类型化 402/429 错误（详情）
• 仅 2 个运行时依赖项 — @modelcontextprotocol/sdk + zod；使用原生 fetch

快速开始

需要 Node.js 22 或更高版本，以及 IDEOGRAM_API_KEY — 在 Ideogram 的 API 控制台中创建密钥：ideogram.ai/platform → API Keys → Create key（设置指南）。

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

也可以手动配置（如下）。npm install -g @qmediat.io/ideogram-mcp 会安装 ideogram-mcp 命令，可用于替换任何配置中的 npx 行。

配置

Claude Code

添加到 ~/.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

添加到 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"
      }
    }
  }
}

环境变量

变量	必需	默认值	说明
IDEOGRAM_API_KEY	是	—	你的 Ideogram API 密钥（ideogram.ai/platform → API Keys）
IDEOGRAM_OUTPUT_DIR	否	/tmp/ideogram-output	用于保存图像的任意文件夹。请使用绝对路径（例如 /home/user/images/ideogram）

可用工具

工具	功能	模型
ideogram_generate	根据文本提示词生成图像	ideogram-3（默认）、ideogram-4-5、ideogram-4、ideogram-3-character、ideogram-3-custom-model、ideogram-4-custom-model、ideogram-3-transparent、ideogram-4-transparent、ideogram-2a、ideogram-2、gpt-image-2、gpt-image-2-5-flare、gpt-image-2-5-sunburst、nano-banana-2、nano-banana-pro、p-image-ideogram、z-image、auto
ideogram_precise_edit	按图像原始尺寸编辑：提供提示词、可选蒙版（黑色 = 编辑）、最多 4 张参考图像，并通过 context_window 限定编辑范围	ideogram-4-5
ideogram_inpaint	重绘图像的蒙版部分（黑色 = 重绘）	ideogram-3（默认）、ideogram-3-character、ideogram-3-custom-model
ideogram_edit	ideogram_inpaint 在 1.x 中的名称（沿用至 2.x）	同 inpaint
ideogram_remix	根据源图像和提示词生成新图像	ideogram-3（默认）、ideogram-3-character、ideogram-3-custom-model、ideogram-4、auto
ideogram_reframe	将图像扩展至新尺寸（扩图）	ideogram-3（默认）、nano-banana-2
ideogram_replace_background	更换背景，保留主体	ideogram-3（默认）、gpt-image-2
ideogram_remove_background	将前景导出为透明 PNG	ideogram-1
ideogram_remove_object	移除蒙版标记的内容（白色 = 移除）并填补空缺	ideogram-1
ideogram_upscale	放大图像	auto（默认）、topaz-bloom-2、topaz-redefine、topaz-standard-2、topaz-text-refine、topaz-wonder-3-5、nano-banana-pro
ideogram_describe	描述图像：生成文字（ideogram-3，默认）或结构化 JSON 提示词（ideogram-4）	ideogram-3、ideogram-4
ideogram_video_text	根据提示词生成视频：时长、宽高比、分辨率和音频因模型而异；保存为 mp4（填写 duration；若省略，Seedance 将按其最大时长报价）	seedance-2-5-text-to-video（默认）、seedance-2-text-to-video、kling-3-standard-text-to-video、minimax-h3-text-to-video
ideogram_video_image	根据起始图像（以及结束图像）生成视频：支持文件、URL 或资源	seedance-2-5-image-to-video（默认）、seedance-2-image-to-video、kling-3-standard-image-to-video、minimax-h3-image-to-video
ideogram_video_reference	根据参考图像、MP3/WAV 音频片段（Seedance 2.5 为 2-30 秒，其他模型为 2-15 秒）以及存储在 Ideogram 中的视频生成视频；顺序由提示词决定；至少需要一张参考图像或一个视频	seedance-2-5-reference-to-video（默认）、seedance-2-reference-to-video、minimax-h3-reference-to-video
ideogram_layerize	将平面图像转换为可编辑设计：保存不含文字的基础图像，并将检测到的文字块列为 JSON（文本、位置、字体、大小、颜色）；可选提供 font_candidate_files（.ttf、.otf、.woff、.woff2）以进行匹配	ideogram-3
ideogram_ad_localizer	将广告文案翻译成一种语言，同时保留布局、徽标和产品；exact_copy 用于锁定措辞	一个操作（post_ad_localizer）
ideogram_ad_resizer	将广告调整为平台指定的精确广告尺寸，并保持在安全区域内	一个操作（post_ad_resizer）
ideogram_ad_variations	沿一个维度变换广告：人物、场景、群体人数或画面	一个操作（post_ad_variations）
ideogram_colorways	为产品照片重新着色：最多提供 4 个与十六进制颜色配对的蒙版	一个操作（post_colorways）
ideogram_ghost_mannequin	根据服装照片，按要求的视角生成穿在隐形人体模特上的服装图像	一个操作（post_ghost_mannequin）
ideogram_material_swap	将参考材质应用到产品照片的蒙版区域	一个操作（post_material_swap）
ideogram_model_pose_variants	根据指令调整时尚图像中模特的姿势	一个操作（post_model_pose_variants）
ideogram_sketch_to_render	将时尚草图渲染为产品照片	一个操作（post_sketch_to_render）
ideogram_magic_prompt	将提示词改写为 Ideogram 4.0 结构化 JSON 提示词（不生成任何内容）	一个操作（post_magic_prompt_v4）
ideogram_layerize_logos	检测并移除平面设计中的参考徽标：保存基础图像，并列出各图层	一个操作（post_layerize_logos）
ideogram_provenance	检查图像是否由 Ideogram 创建（免费）	一个操作（post_provenance_verify）
ideogram_snap_mask	将手绘蒙版贴合到其标记的对象；保存 PNG	一个操作（post_snap_mask）
ideogram_quote	调用价格：{"tool": "ideogram_generate", "arguments": {…}}	所有支持试运行的操作（不包括 describe、广告变体、姿势变体、草图转渲染以及 v1 实用工具）
ideogram_generation	通过 generation_id 获取生成结果——图像或视频	—
ideogram_usage	Ideogram 报告的计费用量：按产品和货币汇总各明细项目，并传递这些分组（ai-cost 读取的格式）；默认按天统计最近 7 天	—
ideogram_invoices	组织的发票及其明细项目（需要组织管理员密钥）	—
ideogram_api_keys	组织的 API 密钥（已脱敏；需要组织管理员密钥）	—
ideogram_datasets	你的训练数据集：数据集列表（按名称搜索），或单个数据集及其文件和模型	—
ideogram_dataset_upload	将图像、.txt 字幕和 .zip 压缩包上传至数据集（现有数据集，或根据名称新建的数据集）；支持本地路径或公开 https URL	—
ideogram_train	使用包含 15–100 张图像的数据集训练自定义模型；超参数将转到高级操作	ideogram-4（默认）、ideogram-3
ideogram_models	查看你的自定义模型和共享模型，或查看某个模型及其训练运行；已完成模型的 custom_model_uri 可用于通过 ideogram_generate 生成内容	—
ideogram_operations	API 提供的内容：类别、操作、字段和限制	—
ideogram_api	按 ID 调用任何已提供的操作，包括文档索引未列出的操作（reframe 模型 auto、bria-expand、gpt-image-2-5-flare、nano-banana-pro）	—
每个模型的字段都列在工具的架构中（每个模型一种变体），也列在根据规范生成的 docs/API-REFERENCE.md 中。图像输入可以是本地文件路径或公开的 https URL（模型支持时也可以是 Ideogram 资源标识符）；每项操作都适用各自的上传限制。读取任何文件前会先检查每个文件是否符合其字段限制；发送请求前会先检查整个编码请求是否低于请求上限。

无文件客户端：URL 输入和内嵌图像

任何文件字段（image、images、mask、参考图和风格图、字体文件）都可使用公开的 https:// URL 代替本地路径：文件会在该字段各自的大小和类型限制内获取，且仅限公开主机（不允许 IP 地址、本地主机名、私有地址或重定向），并计入调用预算；输入会逐个处理。 在任何会保存图像的工具上设置 inline_images: true，即可将每张小于 3.75 MB 的已保存图像作为图像内容与文本一同返回，每个结果最多 10 MB（其他图像仍以路径形式提供），这样无法读取本机文件的客户端也能看到结果。除非明确要求，否则这两项功能均处于关闭状态。

用量、发票和 Webhook

ideogram_usage 会针对指定范围请求 GET /v2/account/usage（时间使用 RFC 3339 格式；1d 桶最多覆盖 92 天，1h 桶最多覆盖 168 小时——工具会在请求前拒绝更长的范围；来源为 api 和 app），并返回按产品、单位和货币汇总的数值——使用十进制字符串，绝不使用浮点数；无法读取的金额会计入数量，但不会求和——同时将桶数据原样写入输出目录中的 JSON 文件（根据查询命名，仅所有者可读；明细项包含成员电子邮件和密钥前缀；文件小于 64 KB 时也会打印出来）：这是成本工具读取的格式。发票和 API 密钥也会以相同方式写入并显示；不符合规范的响应也会如此处理（会标明这一情况，绝不会报告为成功）。这三个账户工具都需要由组织管理员持有的 API 密钥（Ideogram 会向任何其他密钥返回 404，工具会使用 Ideogram 的原文说明这一点）。

Ideogram 使用 Ed25519 为其 Webhook 签名：规范消息为 request_id\nuser_id\ntimestamp\nsha256_hex(body)， 签名放在 X-Ideogram-Webhook-Signature 中（密钥 ID 放在 X-Ideogram-Webhook-Key-Id 中），公钥为 GET https://api.ideogram.ai/v1/.well-known/jwks.json 返回的 JWKS（公开；最多缓存 24 h）。规范未说明 request_id、user_id 和 timestamp 随请求的哪个部分传递（只列出了两个签名标头）：请按照 Ideogram 的 Webhook 文档，从交付内容中获取这些值。接收方（而非此服务；此服务没有公开 URL）使用此软件包提供的辅助工具进行验证；若交付时间戳与当前时间相差超过 maxAgeS（默认值为 300 s；设置为 Infinity 可关闭此限制），则会拒绝该交付并判定为重放攻击——签名本身永不过期：

import { verifyWebhook } from "@qmediat.io/ideogram-mcp/dist/webhooks.js";
const kid = verifyWebhook(
  { body, requestId, userId, timestamp, signature: headers["x-ideogram-webhook-signature"], keyId: headers["x-ideogram-webhook-key-id"] },
  jwks,
  { maxAgeS: 300 },
);
if (kid === null) reject(); // the key id that verified, else null

训练自定义模型

放入一个包含参考资料的文件夹：ideogram_dataset_upload {"name": "brand refs", "files": ["…/1.png", "…/1.txt", "…/more.zip"]} 会创建数据集并上传资源（字幕侧文件 x.txt 会与 x.png 配套；压缩包可以同时包含两者）， ideogram_train {"dataset_id": "…", "model_name": "Brand Refs"} 会启动 Ideogram 4.0 训练（对于 3.0，使用 "model": "ideogram-3"；training_steps、lora_rank、ema、learning_rate——以及 4.0 的 batch_size、base_variant、wandb_project——会转交给高级操作），ideogram_models {"model_id": "…"} 会跟踪训练进度；已完成模型的 custom_model_uri 可通过 ideogram_generate 生成图像，并使用 model: "ideogram-4-custom-model"。Ideogram 会根据套餐对训练收费；工具会说明启动了什么，绝不会重复启动。

等待并稍后收取

生成请求会异步发送，并在 Ideogram 接受后立即返回。随后，工具会等待最多 wait_s 秒（默认 45 秒，最多 50 秒：MCP 客户端会在 60 秒时让调用超时），每隔 2 秒轮询一次，间隔按 ×1.5 增长，最长可达 30 秒。等待结束时仍在运行的任务会返回其 generation_id：ideogram_generation {"generation_id": "…"} 可在稍后（本会话或其他会话中）收取结果。再次发送请求会启动第二个任务，并产生第二笔费用。 每次工具调用都有一份预算，在调用开始时固定为 55 秒（调用方的 60 秒减去余量），若调用方主动取消（客户端超时或用户取消），则会提前结束。该调用的每次请求、重试等待（包括 Retry-After）、轮询和下载都会计入剩余预算，因此调用中的任何操作都不会超出调用方的时限；调用方放弃后，创建任务的请求绝不会重发：只有剩余时间足以完成一次与刚被拒绝的尝试耗时相同的尝试时，才会重发 POST。预算耗尽而中断的下载会在生成 ID 旁标记为未保存；ideogram_generation 会在新的调用中保存该结果。由此带来的限制是：耗时超过 55 秒的上传无法在一次 MCP 调用中完成；预算在请求进行期间耗尽时，会报告请求可能已被接受（绝不重发）；而在调用方放弃后 API 才接受的任务，其 ID 将无人收到——这是 60 秒客户端时限造成的限制，并非此服务所致。

价格

ideogram_quote 会使用 Ideogram 的 dry_run，发送与工具实际发送的请求完全相同的内容：响应会给出以美元和积分计价的价格（按你的账户积分费率），并标明是精确值还是带上限的估算值；不会生成、存储或计费。Describe 不支持 dry run，因此无法报价。生成完成后，会显示 Ideogram 报告的费用。本服务不保存价格表：价格由 API 按请求决定。

与 1.x 的兼容性

为 1.x 编写的调用在 2.x 中仍可正常使用，结果会说明进行了哪些映射：

1.x 输入	2.0
不带 model 的 ideogram_generate	与之前相同，为 ideogram-3
model: "3.0" / "4.0"	ideogram-3 / ideogram-4
rendering_speed: "TURBO" / "DEFAULT" / "QUALITY"	对接受 rendering_speed 的模型，映射为 turbo / default / quality；对接受 quality 的模型，映射为 quality: low / medium / high（Ideogram 4.5、GPT Image 2.5、P-Image）
rendering_speed: "FLASH"	拒绝（v2 不支持 FLASH）——对支持该选项的模型使用 quality: very_low
大写的 magic_prompt、style_type、color_palette.name	转为小写
ideogram_edit	ideogram_inpaint
describe_model_version: "V_3"	model: "ideogram-3"

所选 v2 模型不接受的 1.x 字段会被拒绝，并列出接受该字段的模型（变更日志中有完整表格）。

原始调用

ideogram_api 可按操作 ID 执行此版本提供的任何操作——精选操作以及所有其他 /v2/image 操作（文档索引中未列出的 reframe 模型），并将参数保留在各自的位置：{"operation": "…", "params": {"path": {}, "query": {}, "body": {}}, "files": [{"field": "image", "path": "…"}], "dry_run": false}。发送任何内容之前，都会根据操作自身的架构和规则检查参数。Ideogram 文档未列出的操作需要设置 allow_undocumented: true；web-app（Bearer）和内部操作会被拒绝；账户系列中未记录的 get_asset_reference_usage 也会被拒绝；客户专属工具（skechers、swan、sole-swap）和仅在规范中定义的工作流只在此处运行，且必须启用 allow_undocumented；v1 模型变体（ernie、flux-2 klein、Ideogram 4.0 各档、P-Image 各档、design 和 graphic v3/v4）无需启用此选项即可在此处运行——Ideogram 在其 v1 参考文档中记录了这些模型（如果有对应的 _async 版本，优先使用该版本：同步 v1 生成必须在调用的时间预算内完成）；后续版本没有计划安排任何内容（计划）。

安全

采用防御性、最小依赖的设计：

• SSRF 防护 — 仅通过 HTTPS 从允许列表中的主机下载，禁止重定向；作为输入提供的 URL 仅从公共主机获取（不接受 IP 字面量、本地名称、解析后属于私有或特殊用途的地址，也不接受重定向），下载必须在调用的时间预算内完成，且连接固定到已判定的地址（DNS 重绑定不会造成任何影响）

• 拒绝符号链接 — 读取前，lstat() 会拒绝符号链接输入文件（符号链接父目录会先解析）

• 按操作限制上传 — 读取任何文件前，都会使用 stat() 根据对应字段的限制检查每个文件；不会发送本地文件名（文件会以 <field>.<ext> 的形式发送）——训练资源自带的名称除外（绝不发送其目录），因为 API 会根据该名称匹配说明文字

• 流式、限量下载 — 下载内容写入磁盘时会统计字节数，达到 50 MB 时停止（视频为 512 MB），并删除未完整下载的文件；若视频无法在调用的时间预算（55 秒）内下载完成，则会显示“未保存”及其链接，供你在链接过期前自行获取；仅接受 image/* 或 video/mp4

• 架构校验 — 发出任何请求前，都会根据每个模型生成的架构校验输入；如果成功响应不符合规范中的架构，则会报告契约不匹配，绝不会将其报告为成功

• 输入路径 — 模型可以指定机器上任何可读取的图像文件进行上传；请以仅能读取你愿意发送给 Ideogram 的图像的用户身份运行服务

完整详情请参阅 SECURITY.md。

开发

git clone https://github.com/qmediat/ideogram-mcp.git
cd ideogram-mcp
npm install
npm run build
npm run typecheck
npm run lint        # structure rules, repeated blocks, the baseline ratchet (docs/SYSTEMIC.md §1)
npm run format      # Prettier (npm run lint checks it)
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)

规范快照用于驱动代码：运行 npm ci --prefix scripts/spec-gen && npm run spec:generate 可重新生成 src/generated/（CI 会通过 npm run spec:check 检查该目录），运行 npm run docs:api 可生成 API 参考文档，运行 npm run spec:pull 可将实时规范与快照进行比较。这些脚本需要 Node.js 22.18 或更高版本（类型剥离），npm run lint 也需要此版本 （其 Babel 8 解析器要求 22.18+ 或 24.11+）。 设置 IDEOGRAM_API_KEY 后，test/live-dry-run.test.mjs 会为每个精选模型报价，不产生费用，并将价格写入 docs/PRICES-<date>.md。

本地运行：

IDEOGRAM_API_KEY=your-key node dist/index.js

贡献

架构指南和 PR 要求请参阅 CONTRIBUTING.md。

商标与关联关系

Ideogram 是 Ideogram 的商标。这是由 Quantum Media Technologies sp. z o.o. 发布并由社区独立维护的集成；它与 Ideogram 无关联，也未获得 Ideogram 的赞助或认可。通过此服务使用 Ideogram API 时，须遵守 Ideogram 自身的条款，并使用您自己的 API 密钥或账户。

许可证

MIT — Quantum Media Technologies

---

由 Quantum Media Technologies 制作 · 更多来自 qmediat 的开源项目