Muse Image

muse-image-mcp

English · 繁體中文 · 简体中文

Meta Muse 画像モデルを利用した画像生成機能を、Claude Code、Claude Desktop、Cursor などの MCP 対応エージェントに提供する MCP サーバーです。

できること

会話で画像を扱う一連の作業をカバーする3つのツールです。

ツール	用途
generate_image	テキストから画像を生成します。1回の呼び出しで1〜10枚生成できます。
edit_image	参照画像（ローカルファイルまたはURL）をもとに編集します。
iterate_image	会話を通じて調整します。「もっと暖色にして」と言い続けると、その指示を記憶します。

このサーバーを使う理由

コンテキストウィンドウを圧迫しません。 すべてのツールは画像をディスクに書き込み、画像のバイト列ではなく絶対ファイルパスを返します。画像を12枚生成しても、コンテキストを消費するのは数十行ではなく、パスを示す12行だけです。画像を実際に確認したい場合は、ファイル読み取りツールでパスを開いてください。

状態を保持せずに複数ターンで調整できます。 iterate_image は response_id を返します。それを previous_response_id として渡すと、次のターンで同じ会話を継続できます。サーバー自体には何も保存されません。会話の状態は Meta 側にあるため、サーバーは再起動可能でステートレスなままです。

新しいモデルへの対応に新しいリリースは必要ありません。 MUSE_MODEL または呼び出しごとの model パラメーターでモデルを切り替え、サーバーが認識していないパラメーターは extra_params 経由で渡せます。リクエスト構造を決定するフィールドは上書きできないよう保護されており、それ以外のフィールドは意図的に自由に指定できます。

コストを常に把握できます。 すべてのレスポンスの末尾に、その呼び出しの推定コストが表示されます。

必要条件

• Node.js >= 20.12.0
• Meta Muse API キー

API キーの取得

Muse Image はMeta Model API上で動作するため、このプロジェクトではなく Meta に登録します。

1. https://dev.meta.ai にアクセスし、Meta Model API ダッシュボードにサインインします。
2. API keys を開きます。
3. Create API key をクリックして、キーの値をコピーします。

この値を、以下で MUSE_API_KEY として渡します。Meta のドキュメントではこの変数を MODEL_API_KEY としていますが、このサーバーでは MUSE_API_KEY として読み取り、https://api.meta.ai/v1 に接続し、デフォルトで muse-image-1.0 モデルを使用します。

参考： Model API docs · Image generation · Muse Image announcement

キーはソース管理に含めないでください。以下で説明する MCP 設定の env ブロックまたは .env ファイルを使用してください。

インストール

オプション1：npx（推奨 — クローン不要）

claude mcp add muse-image --scope user --env MUSE_API_KEY=your-key -- npx -y muse-image-mcp

npx は必要に応じて最新バージョンを取得して実行するため、事前のインストールは不要です。

• --scope user はすべてのプロジェクトに適用されます。現在のプロジェクトだけに適用するには --scope local を使用してください。
• -y は npx のインストール確認を省略します。指定しないと、インタラクティブな質問でサーバーが停止し、ハンドシェイクに失敗します。
• -- の後ろはすべて起動コマンドです。その前の --env は claude mcp add に属します。

その他の MCP クライアント（Claude Desktop、Cursor）では、設定を手動で記述してください。

{
  "mcpServers": {
    "muse-image": {
      "command": "npx",
      "args": ["-y", "muse-image-mcp"],
      "env": { "MUSE_API_KEY": "your-key" }
    }
  }
}

Windows で npx が見つからない場合は、"command": "cmd" と "args": ["/c", "npx", "-y", "muse-image-mcp"] を使用してください。

オプション2：ローカルクローン（コードを変更する場合）

git clone https://github.com/kevintsai1202/muse-image-mcp.git
cd muse-image-mcp
npm install
npm run build
claude mcp add muse-image --scope user --env MUSE_API_KEY=your-key -- node <your-clone-path>/dist/index.js

インストール後

新しいセッションを開始してください。 MCP サーバーはセッション開始時に読み込まれるため、既存のセッションでは認識されません。次に claude mcp list を実行して muse-image: ... - Connected と表示されることを確認し、3つの mcp__muse-image__* ツールが利用可能であることを確認してください。

API キーの設定

優先順位はMCP 設定の env ブロック > .env ファイルです。

MCP 設定の env ブロックを使用する（npx でインストールした場合の唯一の方法）

上記の --env MUSE_API_KEY=your-key を参照してください。

.env ファイルを使用する

サーバーは次の場所を順番に検索し、最初に見つかったファイルを使用します。

1. <package root>/.env — ローカルクローンに便利です
2. ~/.muse-image-mcp/.env — npx でインストールした場合に制御できる唯一の場所です

MUSE_API_KEY=your-key

.env は Claude Code を起動したディレクトリからは読み込まれない点に注意してください。MCP サーバーの作業ディレクトリはクライアントによって決まるため、設定場所として適していません。npx でインストールした場合、パッケージはハッシュ化された npm キャッシュディレクトリに配置され、クリーンアップされるため、そこに .env を置いても意味がありません。

環境変数

以下はすべて、.env または MCP 設定の env ブロックで使用できます。

変数	必須	デフォルト	説明
MUSE_API_KEY	はい	—	API キーです。指定しない場合、サーバーはただちに終了し、stderr に理由を出力します
MUSE_MODEL	いいえ	muse-image-1.0	グローバルなデフォルトモデル ID
MUSE_EXTRA_PARAMS	いいえ	{}	JSON オブジェクト文字列 — グローバルなデフォルト追加パラメーター
MUSE_OUTPUT_DIR	いいえ	<cwd>/generated-images	出力ディレクトリです。存在しない場合は作成されます
MUSE_BASE_URL	いいえ	https://api.meta.ai/v1	API のベース URL
MUSE_TIMEOUT_MS	いいえ	120000	リクエストごとのタイムアウト（ミリ秒）

MUSE_OUTPUT_DIR のデフォルト値にある cwd は、MCP クライアントがサーバーを起動した作業ディレクトリです。Claude Code の場合はセッションのプロジェクトルートなので、画像はそのプロジェクトの generated-images/ に保存されます。クライアントの動作が異なる場合や、固定の保存先を指定したい場合は、MUSE_OUTPUT_DIR に絶対パスを設定してください。

v0.1.0 以降、デフォルトの出力ディレクトリは muse-output/ から generated-images/ に変更されました。以前のディレクトリは自動的に削除または移行されません。

モデルの切り替えと新しいパラメーターの指定

新しいモデルがリリースされても、このプロジェクトの更新を待つ必要はありません。環境変数でモデルを切り替え、extra_params で新しいパラメーターを渡せます。

モデルの切り替え

.env または MCP 設定でグローバルに指定します。

MUSE_MODEL=muse-image-2.0

呼び出しごとに指定する場合は、会話で依頼するだけでエージェントが model を渡します。

{ "prompt": "a red fox", "model": "muse-image-2.0" }

新しいパラメーターの指定

JSON オブジェクト文字列でグローバルなデフォルト値を設定します。

MUSE_EXTRA_PARAMS={"quality":"ultra"}

呼び出しごとの上書きは extra_params で行います。グローバル設定とマージされ、呼び出しごとの値が優先されます。

{ "prompt": "a red fox", "extra_params": { "style_preset": "anime" } }

保護されるコアフィールド

model、prompt、response_format、images、input、store、previous_response_id はリクエストの構造を決めるため、extra_params で上書きできません。これらを設定しても効果はなく、応答の末尾に無視されたキーを列挙する警告が表示されます。

モデルを変更するには、extra_params ではなく model パラメーターまたは MUSE_MODEL を使用してください。

これらのコアフィールド以外では、extra_params は n、size、output_format、reasoning_strength など、同名の通常のパラメーターを上書きします。この方法では、ツールスキーマによるこれらの検証（たとえば、n を 1～10 に制限する検証）は適用されません。これは、将来モデルによってパラメーターの意味が変わっても、現在の制限によって妨げられないようにするための意図的な回避策です。この方法で n を上書きする場合は、画像の枚数とコストに注意してください。

ツール

すべてのツールは画像をローカルに保存し、画像そのものではなく絶対パスを返します。これにより、会話コンテキストに base64 が含まれるのを防げます。画像を確認するには、ファイル読み取りツールでそのパスを開いてください。

generate_image — テキストから画像を生成

パラメーター	必須	デフォルト	説明
prompt	はい	—	画像の説明
n	いいえ	1	画像の枚数、1～10
size	いいえ	—	1792x1024 のようなアスペクト比を表す文字列。正確なピクセル解像度ではありません
output_format	いいえ	png	png / webp / jpeg
reasoning_strength	いいえ	high	high / low — 料金は同じです
filename_prefix	いいえ	muse	出力ファイル名のプレフィックス
model	いいえ	—	モデル ID。省略するとサーバーのデフォルトが使用されます（MUSE_MODEL を参照）
extra_params	いいえ	—	追加パラメーターのオブジェクト。呼び出しごとの値を優先して MUSE_EXTRA_PARAMS とマージされます。コアフィールドは保護されます（上記を参照）

edit_image — 参照画像から編集

パラメーター	必須	デフォルト	説明
prompt	はい	—	画像の説明
images	はい	—	ローカルファイルパス（png/jpg/jpeg/webp/gif）または http(s) URL の配列。ローカルファイルは自動的に base64 エンコードされます
n	いいえ	1	画像の枚数、1～10
size	いいえ	—	1792x1024 のようなアスペクト比を表す文字列。正確なピクセル解像度ではありません
output_format	いいえ	png	png / webp / jpeg
reasoning_strength	いいえ	high	high / low — 料金は同じです
filename_prefix	いいえ	muse-edit	出力ファイル名のプレフィックス
model	いいえ	—	モデル ID。省略するとサーバーのデフォルトが使用されます
extra_params	いいえ	—	上記と同じマージおよび保護ルールが適用されます

iterate_image — 会話形式での調整

パラメーター	必須	説明
prompt	はい	今回の指示
previous_response_id	いいえ	前のターンで返された ID。新しい会話を開始する場合は省略します
images	いいえ	最初のターンで使用する参照画像
reasoning_strength	いいえ	デフォルトは high です
size	いいえ	1024x1536 のようなアスペクト比を表す文字列
output_format	いいえ	png / webp / jpeg。ほかの2つのツールとは異なり、省略すると webp が返されます。これはこのエンドポイントにおける Meta のデフォルトです
filename_prefix	いいえ	デフォルトは muse-iter です
model	いいえ	モデル ID。省略するとサーバーのデフォルトが使用されます
extra_params	いいえ	上記と同じマージおよび保護ルールが適用されます

このツールには n パラメーターがありません。/v1/responses エンドポイントは1ターンにつき画像を1枚返します。size と output_format には対応していますが、トップレベルではなく、リクエストの tools エントリー内で送信されます。以下の調査結果を参照してください。

レスポンスには必ず response_id が含まれます。同じ会話を続けるには、次の呼び出しでその値を previous_response_id として渡してください。このサーバーは会話状態を保存しません。Meta が保存します。

/v1/responses の調査結果

リクエスト本文：画像ごとの設定は tools 内に指定

このエンドポイントでは、reasoning_strength、size、output_format はトップレベルのパラメーターではなく、image_generation ツールのエントリーに属します。トップレベルで reasoning_strength を送信すると、単に無視されるのではなく、API がリクエスト全体を拒否します。

HTTP 400 — unknown parameter `reasoning_strength`

正しい形式：

{
  "model": "muse-image-1.0",
  "input": "now make the background deep navy",
  "store": true,
  "previous_response_id": "resp_abc123",
  "tools": [
    { "type": "image_generation", "reasoning_strength": "low", "size": "1024x1536", "output_format": "png" }
  ]
}

0.1.0 までのバージョンでは reasoning_strength をトップレベルで送信していたため、iterate_image は呼び出しのたびに失敗していました。generate_image と edit_image には影響していません。これらは /images/generations と /images/edits を使用しており、そこではこれらの値を正当なトップレベルパラメーターとして指定できます。

これにより、この README の以前の記述も訂正されます。size と output_format はここでサポートされています。output_format: "png" を指定すると、エンドポイントのデフォルトである webp ではなく、正真正銘の PNG が返されます（base64 ヘッダーで確認済み）。本当に指定できないのは n だけで、1ターンにつき画像は1枚です。

scripts/probe-responses-api.mjs で、仮説ごとに1ケースずつ、稼働中の API に対して以上の内容を再現できます。

レスポンスの形式

Meta は /v1/responses のレスポンススキーマを公開していません。最初の実装は、OpenAI の Responses の規約を参考にした推測に基づくものでしたが、後に実際の API 呼び出しで検証されました。実際の構造は次のとおりです。

{
  "model": "muse-image-1.0",
  "id": "resp_6aa4c23f99592ae0ac454928",
  "object": "response",
  "status": "completed",
  "output": [
    { "type": "reasoning", "summary": [{ "type": "summary_text", "text": "..." }] },
    { "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "" }] },
    { "type": "image_generation_call", "id": "ig_...", "status": "completed", "result": "<base64 image data>" }
  ]
}

推測した形式との違い：

• id の場所：raw.id で正しく、テストで確認できました。変更は不要です。
• 画像データの場所：b64_json フィールドではなく、type === "image_generation_call" の output[] エントリーの result フィールドに、データ URL のプレフィックスなしの生の base64 として格納されています。src/muse-client.ts の extractB64Images は現在、b64_json（ほかの形式の可能性に備えて維持）と、この検証済みの形式の両方を認識します。
• output_format フィールドがない：レスポンスにこのフィールドはありません。元のフォールバックのデフォルト値 "png" は誤りでした。iterate リクエストでは output_format パラメーターを送信しないため、Meta は /images/generations と同じデフォルト値である webp を適用します。返された base64 をデコードすると、正規の WebP ファイルになります（RIFF/WEBP ヘッダー）。フォールバックは現在 "webp" です。

マルチターンの会話を検証済み

実際の API を順に 2 回呼び出しました。まず iterate_image で response_id を取得し、次にその ID を previous_response_id として使用しました。2 回目のターンでは、そのターンで生成された画像 1 枚だけが返されました。1 回目のターンの画像は再送されませんでした。この動作のために、extractB64Images の深い階層を走査するロジックを変更する必要はありませんでした。

（このテスト実行で使用したツールでは、2 回目のターンの生のレスポンスをバイト単位で記録できませんでした。そのため、この結論はバイト単位の比較ではなく、ファイルシステム上の証拠――出力ファイルが 1 つだけで、-2／-3 の接尾辞が付いていないこと――に基づいています。tests/muse-client.test.ts に追加された固定テストでは、先に検証した実際のレスポンス形式を使用しています。）

料金

生成画像 1 枚あたり US$0.01 で、reasoning_strength に関係なく一律です。各ツールのレスポンスには、その呼び出しの推定コストが記載されます。

このサーバーは無料で、MIT ライセンスです。Meta への API 利用料以外に費用はかかりません。

開発

npm test          # Unit tests (never hits the real API)
npm run build     # Compile to dist/
npm run smoke     # Real-API smoke test; needs MUSE_E2E=1 and a real key. Generates 6 images, about US$0.06

ライセンス

MIT © Kevin Tsai