ideogram-mcp について
ideogram-mcpは、Ideogram v2の画像・動画生成や編集、アカウント操作をMCP経由で提供します。モデルごとの入力項目に対応し、生成前の見積もりや長時間ジョブのID取得も行えます。
主な機能
- 01複数モデルでの画像・動画生成
- 02画像編集・インペイント・背景操作
- 03広告制作・商品画像の各種操作
- 04実行前の料金見積もりと非同期ジョブ取得
- 05使用状況・請求書・キー・カスタムモデル訓練
活用シーン
- 01画像や動画の生成・修正
- 02広告のローカライズやキャンペーン素材のリサイズ
- 03アカウント使用状況の確認と請求書の取得
- 04カスタム画像モデルの訓練と利用
MCP 対応
Ideogramプラットフォームの厳選された操作と、スキーマ検証済みのAPI呼び出しをMCPクライアント向けツールとして提供します。クライアントはIdeogram APIキーを使い、stdioで接続します。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
npx -y @qmediat.io/ideogram-mcpIDEOGRAM_API_KEYシークレットYour Ideogram API key (create one at https://ideogram.ai/platform)IDEOGRAM_OUTPUT_DIRDirectory for saved images (default: /tmp/ideogram-output)ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。
ツール
12掲載時のツール一覧 · 2 週間前に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| mask | any | いいえ | ソースと同じサイズのローカルマスク画像ファイル |
| seed | any | いいえ | 再現可能な結果を得るための乱数シード |
| size | any | いいえ | 出力サイズ:「auto」、「source」(ソース画像が必要)、または WIDTHxHEIGHT |
| model | enum | いいえ | モデル(デフォルトは ideogram-3)。各モデルは、以下の対応するバリアントのフィールドを使用しますauto | gpt-image-2 | gpt-image-2-5-flare | gpt-image-2-5-sunburst | ideogram-2 | ideogram-2a | ideogram-3 | ideogram-3-character | ideogram-3-custom-model | ideogram-3-transparent | ideogram-4 | ideogram-4-5 | ideogram-4-custom-model | ideogram-4-transparent | nano-banana-2 | nano-banana-pro | p-image-ideogram | z-image |
| images | any | いいえ | ローカルのソース画像ファイル(最初の画像が編集対象) |
| prompt | any | いいえ | 作成または変更する内容を自然言語で指定します |
| wait_s | integer | いいえ | 結果を待つ秒数(0~50、デフォルトは 45)。まずジョブが受け付けられます。待機終了時も実行中の場合、結果は ideogram_generation 用の generation_id です(再送信も二重課金もありません)。 |
| quality | any | いいえ | very_low、low、medium、high:品質が高いほど料金も高くなります |
| num_images | any | いいえ | 生成する画像の枚数(1 枚ごとに課金されます) |
| resolution | any | いいえ | モデルのリストにある正確な出力サイズ WIDTHxHEIGHT。aspect_ratio とは併用できません |
| style_type | any | いいえ | ビジュアルスタイルの種類 |
| style_codes | any | いいえ | 8 桁の 16 進数スタイルコード |
| aspect_ratio | any | いいえ | 出力アスペクト比(例:16x9)。resolution とは併用できません |
| magic_prompt | any | いいえ | auto、on、off:Ideogram にプロンプトを書き換えさせます |
| style_preset | any | いいえ | 名前付きスタイルプリセット。style codes または style references とは併用できません |
| color_palette | any | いいえ | 名前で指定するプリセットパレット、または重み付きの 16 進数カラー |
| upscale_factor | any | いいえ | x2、x4、x8 |
| negative_prompt | any | いいえ | 画像に含めない内容 |
| rendering_speed | any | いいえ | turbo、default、quality:処理が速いほど料金が安くなります |
| resolution_tier | any | いいえ | 出力解像度の段階 |
| custom_model_uri | any | いいえ | 自分でトレーニングしたカスタムモデル、またはアクセス権を与えられたモデル |
| style_reference_images | any | いいえ | 結果のスタイル参照に使用するローカル画像ファイル |
| image_asset_identifiers | any | いいえ | ローカルのソース画像の代わりに使用する Ideogram アセット |
| character_reference_mask | any | いいえ | 参照画像内のキャラクターの位置を示すローカルのグレースケールマスク |
| character_reference_images | any | いいえ | キャラクターの一貫性を保つためのローカル画像ファイル |
| enable_copyright_detection | any | いいえ | 結果に Ideogram の著作権検出を実行します(遅延が増加します) |
| style_reference_collection_id | any | いいえ | 適用する保存済みスタイルコレクション |
| style_reference_asset_identifiers | any | いいえ | スタイル参照として使用する Ideogram のアセット(アップロードまたは以前の結果) |
| character_reference_asset_identifiers | any | いいえ | キャラクター参照として使用する Ideogram のアセット |
| style_reference_collection_version_id | any | いいえ | 保存済みスタイルコレクションのバージョン |
詳細
@qmediat.io/ideogram-mcp
v2 API を通じて Ideogram プラットフォームを利用する MCP サーバーです。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)を、1 つの API キーで利用できます。生成、精密編集、インペイント、リミックス、リフレーム、背景の置換・削除、オブジェクトの削除、アップスケール、説明、レイヤー化、プロンプト・画像・参照画像からの動画生成に加え、商用ツール(広告のローカライズ、リサイズとバリエーション、カラーバリエーション、ゴーストマネキン、素材の置換、モデルポーズのバリエーション、スケッチからレンダリング)、ユーティリティ(マジックプロンプト、ロゴのレイヤー化、来歴、スナップマスク)、さらにアカウントの使用状況、請求書、キー、カスタムモデルのトレーニングも、Claude Code、Claude Desktop、または stdio 経由の任意の MCP クライアントから利用できます。各呼び出しは事前に料金を確認でき(API 独自のドライラン)、時間のかかるジョブは ID で返され、後から取得できます。また、このリリースが提供するその他の操作も、検証済みの raw 呼び出しで実行できます。Ideogram の OpenAPI 仕様をもとに構築されています(ADR-0001)。
このサーバーを選ぶ理由
- 単一モデルではなく、プラットフォーム全体に対応 — すべてのツールで
modelを指定でき、各モデル固有のフィールドを利用できます(モデルが対応していないフィールドは拒否され、対応モデルが示されます)。モデルとフィールドの一覧は Ideogram の仕様に基づいているため、新しいモデルへの対応は書き直しではなく、レビュー済みスナップショットの更新で済みます - 支払い前に料金を確認 —
ideogram_quoteで、今回の呼び出しにかかる正確な料金を API に問い合わせます(USD とクレジット。生成も請求も発生しません) - デフォルトで非公開 —
privateに対応するすべての厳選ツールは、明示的に設定しない限りtrueを送信します(背景削除、背景置換、およびautoモデルでは、API 独自のデフォルトがプランの設定になります)。このフィールドのないモデル(Ideogram 3.0 によるリフレーム、オブジェクト削除)は API 独自の動作に従い、ideogram_apiは指定された値をそのまま送信します - 二重請求なし — Ideogram がジョブを受け付けた時点で返されます。ツールは
wait_sの時間だけ待機し、それを超える場合はgeneration_idを返してideogram_generationで取得できるようにします。リクエストを再送するのは、マシンから送信されなかった場合、または 429 が返された場合に限られます - それ以外もすべて検証済み —
ideogram_operationsで API が提供する操作を一覧表示できます。ideogram_apiでは、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 キー → キーを作成 から作成してください(セットアップガイド)。
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に保存された動画をプロンプト順に使用して動画を生成します。参照画像または動画が少なくとも1つ必要です | 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 | 広告のレイアウト、ロゴ、商品を保ったまま、コピーを1つの言語に翻訳します。exact_copyで文言を固定できます | 1つの操作(post_ad_localizer) |
ideogram_ad_resizer | 広告をプラットフォーム指定の正確な広告サイズに、安全領域内でリフレームします | 1つの操作(post_ad_resizer) |
ideogram_ad_variations | 人物、設定、グループの人数、シーンのいずれか1つの軸に沿って広告を変化させます | 1つの操作(post_ad_variations) |
ideogram_colorways | 商品写真の色を変更します。最大4つのマスクに、それぞれ16進カラーコードを指定できます | 1つの操作(post_colorways) |
ideogram_ghost_mannequin | 衣服の写真から、指定した視点で透明マネキンに着せた画像を生成します | 1つの操作(post_ghost_mannequin) |
ideogram_material_swap | 商品写真のマスク領域に参照素材を適用します | 1つの操作(post_material_swap) |
ideogram_model_pose_variants | 指示に従ってファッション画像のモデルのポーズを変更します | 1つの操作(post_model_pose_variants) |
ideogram_sketch_to_render | ファッションスケッチを商品写真としてレンダリングします | 1つの操作(post_sketch_to_render) |
ideogram_magic_prompt | プロンプトをIdeogram 4.0の構造化JSONプロンプトに書き換えます(生成は行いません) | 1つの操作(post_magic_prompt_v4) |
ideogram_layerize_logos | フラットデザインから参照ロゴを検出して削除します。ベース画像を保存し、レイヤーを一覧表示します | 1つの操作(post_layerize_logos) |
ideogram_provenance | 画像がIdeogramによって作成されたか確認します(無料) | 1つの操作(post_provenance_verify) |
ideogram_snap_mask | 手描きのマスクを対象物に合わせて調整し、PNGを保存します | 1つの操作(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など) | — |
| 各モデルのフィールドは、ツールのスキーマ(モデルごとに1つのバリアント)と、仕様から生成された 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 です)。製品、単位、通貨ごとの合計を返します。値は小数文字列であり、浮動小数点数は使いません。読み取れない金額は計上されますが、合計には含まれません。また、バケットは Ideogram が送信したとおりに出力ディレクトリ内の JSON ファイルへ書き込まれます(クエリ名を付け、所有者のみが読み取り可能。明細にはメンバーのメールアドレスとキーのプレフィックスが含まれるため、64 KB 未満の場合は画面にも出力されます)。これはコストツールが読み取る形式です。請求書と API キーも同じ方法で書き込まれ、表示されます。仕様に沿わない応答も同様に扱われ、成功としてではなく、その旨が報告されます。3 つすべてのアカウントツールには、組織の管理者が所有する 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 時間キャッシュできます)。request_id、user_id、timestamp の送信方法は仕様に記載されていません(署名ヘッダー 2 つのみが記載されています)。Ideogram の Webhook ドキュメントに従って、配信データから取得してください。受信側が、このパッケージに付属するヘルパーを使って検証します。公開 URL を持たないこのサーバーでは検証しません。タイムスタンプが現在時刻から maxAgeS(デフォルトは 300 秒。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": "…"} で進捗を確認し、COMPLETED 状態のモデルの 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": "…"} を呼び出すと、このセッションまたは別のセッションで後から取得できます。リクエストを再送信すると、2 つ目のジョブが開始され、料金も 2 回分発生します。
各ツール呼び出しには、開始時に固定される予算が 1 つあります。呼び出し元の 60 秒から余裕分を差し引いた 55 秒で、呼び出し元によるキャンセル(タイムアウトするクライアント、またはキャンセルするユーザー)があれば、それより早く終了します。リクエスト、再試行までの待機時間(Retry-After を含む)、ポーリング、ダウンロードはすべて、残りの予算内で行われるため、呼び出し元の終了後も処理が続くことはありません。また、呼び出し元が諦めた後に、処理を開始するリクエストが再送信されることもありません。POST の再送信は、直前に拒否された試行と同じ長さの試行を行えるだけの時間が残っている場合に限られます。予算切れでダウンロードできなかったファイルは、generation id の横に未保存として表示されます。ideogram_generation は新しい呼び出しでそのファイルを保存します。この仕組みでも解決できない点があります。55 秒を超えるアップロードは 1 回の MCP 呼び出しでは処理できません。処理中に予算が切れたリクエストは、受け付けられた可能性があるとして報告され、再送信されません。また、呼び出し元が諦めた後に API が受け付けたジョブは、誰にも渡されない ID を保持します。これは 60 秒でタイムアウトするクライアント側の制限であり、このサーバーの制限ではありません。
価格
ideogram_quote は、dry_run を指定してツールが送信するものとまったく同じリクエストを Ideogram に送信します。回答には、USD とクレジット(アカウントのクレジット単価で計算)の価格が、exact または上限付きの estimate として返されます。生成、保存、課金は一切行われません。Describe には dry run がないため、見積もりを取得できません。生成が完了すると、Ideogram が報告した費用が表示されます。このサーバーは価格表を保持しておらず、価格はリクエストごとの API 価格です。
1.x との互換性
1.x 向けに書かれた呼び出しは 2.x でも引き続き動作し、結果にはどのようにマッピングされたかが示されます。
| 1.x の入力 | 2.0 |
|---|---|
ideogram_generate で model を指定しない場合 | 以前と同様に ideogram-3 |
model: "3.0" / "4.0" | ideogram-3 / ideogram-4 |
rendering_speed: "TURBO" / "DEFAULT" / "QUALITY" | rendering_speed を受け取るモデルでは turbo / default / quality、quality を受け取るモデル(Ideogram 4.5、GPT Image 2.5、P-Image)では quality: low / medium / high |
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 のフィールドは、対応するモデルとともに拒否されます(全テーブルはchangelogをご覧ください)。
生の呼び出し
ideogram_api は、このリリースで提供されるあらゆる操作を、その ID とパラメーターを所定の位置に保ったまま実行します。厳選された操作だけでなく、その他すべての /v2/image 操作(ドキュメントのインデックスに掲載されていないリフレームモデルも含みます)が対象です。形式は {"operation": "…", "params": {"path": {}, "query": {}, "body": {}}, "files": [{"field": "image", "path": "…"}], "dry_run": false} です。送信前に、各操作固有のスキーマとルールに照らしてパラメーターを検証します。Ideogram のドキュメントに掲載されていない操作には allow_undocumented: true が必要です。Web アプリ(Bearer)および内部操作は拒否されます。account ファミリーの非公開操作 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 リファレンスに記載されています(同期版の v1 生成は呼び出しの制限時間内に完了する必要があるため、対応する _async 版がある場合はそちらを優先してください)。後のリリースに持ち越す予定はありません(計画)。
セキュリティ
防御的で、依存関係を最小限に抑えた設計です。
- 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 API を利用する際は、Ideogram 独自の利用規約と、ご自身の API キーまたはアカウントが適用されます。
ライセンス
MIT — Quantum Media Technologies
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。