An MCP server that gives Claude Code, Claude Desktop and Cursor image generation powered by the Meta Muse model — and returns file paths instead of base64, so your context window survives.
一個 MCP server，讓 Claude Code、Claude Desktop 與 Cursor 用 Meta Muse 模型生圖。回傳的是檔案路徑而不是 base64，你的 context 不會被圖片吃光。
Three modes三種模式
The three tools differ in one thing that matters more than the rest: whether the model remembers what you said last turn.
三個工具最關鍵的差別只有一個：模型記不記得你上一輪說過什麼。
Text in, images out. Use it for the first image of anything — and when you want several takes at once, since it's the only mode that returns up to 10 in a single call.
送文字、拿圖。任何東西的第一張都用它。也只有這個模式一次能回最多 10 張，想一次看好幾種版本時特別合用。
Hand it an existing image — a local path or a URL — plus a full description of the change. Each call stands alone, so it's the right choice when you can state the target precisely. Multiple inputs compose into one scene.
給它一張既有的圖（本機路徑或網址），加上完整的修改描述。每次呼叫各自獨立，所以當你講得出明確目標時該用它。也可以丟多張圖合成同一個畫面。
The only mode with memory. Say warmer
, then too much, back off
, and it knows what you're talking about. Use it when you can't yet describe the destination, only the direction.
唯一有記憶的模式。說「再暖一點」，接著說「太過頭了，收回來一些」，它知道你在講什麼。當你還說不出想要什麼、只說得出方向時用它。
| generate_image | edit_image | iterate_image | |
|---|---|---|---|
| Remembers previous turns記得前幾輪 | No否 | No否 | Yes — via是，靠 previous_response_id |
| Input image輸入圖片 | None不需要 | Required, one or more必填，可多張 | Optional, first turn only選填，僅首輪 |
| Images per call單次張數 | 1–10 | 1–10 | 1 |
| Default output format預設輸出格式 | png | png | webp |
| Endpoint端點 | /images/generations |
/images/edits |
/responses |
A practical rule.
If you can write the finished result down in one sentence, use edit_image — it's cheaper to reason about and every call is reproducible. If you'd only know it when you see it, use iterate_image and talk your way there one nudge at a time.
一個實用的判準。
如果你能用一句話寫出完成後的樣子，用 edit_image——它比較好推理，而且每次呼叫都可重現。如果你得看到才知道對不對，用 iterate_image，一次推一點地聊到位。
Real output實際產出
Both pairs below came out of this server while this page was being built. They show the difference the comparison table above can only assert.
下面兩組都是做這個頁面時，用這台 server 當場生出來的。上面那張表只能用講的，這裡直接看得到差別。
A weathered brass compass resting on an unfolded antique nautical map, warm afternoon window light, shallow depth of field, photographic still life
Change the warm afternoon light to cold blue moonlight, and add a light mist drifting over the map
One generate_image call, then one edit_image call against its result. The composition, the objects, the camera angle — all survive. Only the light changes, because that's all the instruction asked for.
一次 generate_image，接著對它的結果呼叫一次 edit_image。構圖、物件、視角全都留著，只有光線變了——因為指令只要求了這件事。
A minimalist ceramic vase on a concrete pedestal, soft overcast daylight, clean studio background
Make the vase deep cobalt blue and add a single dried branch
Turn 2 sent one sentence and no image — just the id from turn 1. Notice what changed: not only the colour and the branch, but the vase's shape, the surface it stands on, the whole background. That's the honest difference between the two modes. edit_image preserves the frame; iterate_image continues the conversation and re-renders the scene. Reach for iterate when you're still exploring, and for edit once you know exactly what you want changed.
第二輪只送了一句話，沒有送圖，只帶第一輪的 id。看看變了什麼：不只是顏色和那根枝條，連花瓶的造型、底下的檯面、整個背景都換了。這就是兩個模式老實的差別——edit_image 保留畫面，iterate_image 延續對話並重新渲染整個場景。還在摸索方向時用 iterate，確定要改哪裡時用 edit。
Every image on this page was made by this server. The prism at the top and all four frames here — generated during the build of this page, with the prompts printed next to them. Nothing is stock.
這個頁面上每一張圖都是這台 server 生的。 最上面的稜鏡，以及這裡的四張，都是做這頁時當場生成的，prompt 就印在圖旁邊。沒有一張是圖庫素材。
In practice實際用起來
You don't call the tool. You say what you want, and the agent picks the tool, fills the parameters, and hands you back a path on disk.
你不會去呼叫工具。你只要說你要什麼，Agent 會自己挑工具、填參數，然後把一個檔案路徑交回給你。
Make me a wide hero image of a glass prism splitting light on a dark surface.
幫我做一張寬幅的主視覺，深色檯面上的玻璃稜鏡把光分成光譜。
Cooler. Make it moonlight instead, and add some mist.
冷一點，改成月光，再加一點霧氣。
Paths, not pixels. The agent gets a file path back — a single line of context — and reads the image only if it actually needs to look at it. Generating twenty images costs you twenty lines, not twenty megabytes of base64.
回傳路徑，不是像素。 Agent 拿回的是一個檔案路徑，只佔一行 context；真的需要看圖時才去讀那個檔案。生二十張圖只花掉二十行，而不是二十 MB 的 base64。
A worked example一個完整例子
Two steps, both inside the same conversation: let Claude Code write the explanation first, then have it draw the result. The poster below was made exactly this way.
兩個步驟，都在同一段對話裡完成：先讓 Claude Code 把說明寫清楚，再請它畫出來。下面那張圖就是這樣做出來的。
Claude Code already knows the registration flow from this project's README, so it writes the steps rather than inventing them.
Claude Code 已經從這個專案的 README 讀過註冊流程，所以它是照著寫，而不是自己編。
you — Summarise how to get a Muse API key as four numbered steps, one line each.
你 — 把申請 Muse API key 的流程整理成四個步驟，每步一行。
Name a visual style and the agent turns those steps into a prompt for you. Here the ask was for the look of an old popular-science encyclopedia.
指定一種視覺風格，Agent 會把剛才那些步驟轉成 prompt。這裡要的是舊科普讀物那種插畫感。
you — Now draw those four steps as one diagram, in the style of an old popular-science encyclopedia.
你 — 把這四個步驟畫成一張圖解，用《十萬個為什麼》那種老科普讀物的插畫風格。
Install安裝
Published on npm. npx fetches and runs it on demand — there is nothing to install first.
已發佈到 npm。npx 會在需要時自動抓下來執行，不必先安裝任何東西。
This server uses Node's built-in process.loadEnvFile(), so anything below 20.12.0 fails at startup.
這個 server 用到 Node 內建的 process.loadEnvFile()，低於 20.12.0 會在啟動時就失敗。
node -v
The key is the only required setting. Muse Image runs on the Meta Model API, so you register there, not with this project:
金鑰是唯一必填的設定。Muse Image 跑在 Meta Model API 上，所以你是向 Meta 註冊，不是向本專案註冊：
MUSE_API_KEY.A card comes first. Meta wants a payment method on file before it will issue a key. Usage is priced in US dollars, but you're invoiced in your local billing currency, and the threshold follows that currency — on a Taiwan account it's NT$600. Charges then land on whichever arrives first: hitting that balance, or the monthly close. Meta doesn't publish this in its public docs, so check the figure shown in your own console.
MUSE_API_KEY 的值。要先綁信用卡。 Meta 要求先綁定付款方式才會發給你金鑰。用量以美金計價，但帳單走你當地的結帳幣別，門檻也跟著那個幣別走——台灣帳戶是 NT$600。之後結帳看「累積到這個金額」或「每月結一次」哪個先到。Meta 並未把這個數字寫在公開文件裡，實際門檻請以你自己後台顯示的為準。
Meta's own docs call this variable MODEL_API_KEY; this server reads it as MUSE_API_KEY, and talks to https://api.meta.ai/v1 with the model muse-image-1.0 by default. Reference: Model API docs · Image generation
Meta 官方文件把這個變數叫 MODEL_API_KEY；本 server 讀的名稱是 MUSE_API_KEY，連線到 https://api.meta.ai/v1，預設模型為 muse-image-1.0。參考：Model API 文件 · 影像生成
-y matters — without it npx stops on an interactive prompt and the handshake never completes.
-y 很重要——少了它，npx 會卡在互動詢問，握手永遠完成不了。
claude mcp add muse-image --scope user \ --env MUSE_API_KEY=your-key \ -- npx -y muse-image-mcp
For Claude Desktop or Cursor, write the config by hand instead:
Claude Desktop 或 Cursor 則改成手動寫設定檔：
{
"mcpServers": {
"muse-image": {
"command": "npx",
"args": ["-y", "muse-image-mcp"],
"env": { "MUSE_API_KEY": "your-key" }
}
}
}
MCP servers load at session start. An existing session will not pick it up — this is the most common "I installed it but the tools aren't there".
MCP server 只在 session 啟動時載入，沿用舊的 session 不會生效——這是最常見的「裝好了但工具沒出現」。
You should see muse-image: npx -y muse-image-mcp - Connected, and three mcp__muse-image__* tools available.
應該要看到 muse-image: npx -y muse-image-mcp - Connected，以及三個 mcp__muse-image__* 工具。
claude mcp list
Where do the images go?
By default <cwd>/generated-images, where cwd is whatever directory your client launched the server from — in Claude Code, your project root. Set MUSE_OUTPUT_DIR to an absolute path if you want them somewhere fixed.
圖片會存到哪裡？
預設是 <cwd>/generated-images，而這個 cwd 是你的 client 啟動 server 時所在的目錄——在 Claude Code 就是你的專案根目錄。想固定位置就把 MUSE_OUTPUT_DIR 設成絕對路徑。
Pricing計價
reasoning_strength: high and low cost the same — high is simply slower.reasoning_strength 的 high 與 low 同價，差別只在 high 比較慢。