Muse Image

muse-image-mcp

English · 繁體中文 · 简体中文

一个 MCP 服务，为任何兼容 MCP 的 Agent（Claude Code、Claude Desktop、Cursor）提供由 Meta Muse 图像模型驱动的图像生成功能。

功能介绍

三个工具，涵盖在对话中处理图像的完整流程：

工具	用途
generate_image	文本生成图像。每次调用生成 1–10 张图像。
edit_image	根据参考图像进行编辑——参考图像可以是本地文件或 URL。
iterate_image	通过对话逐步完善图像。持续提出“让它更暖一些”之类的要求，它会记住上下文。

为什么选择此服务

保留上下文窗口空间。 每个工具都会将图像写入磁盘并返回绝对文件路径，而不是图像字节。生成十几张图像只会占用十几行上下文，而不是十几 MB 的 base64 数据。想查看图像时，再用文件读取工具打开对应路径即可。

无需状态即可多轮完善。 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 文档 · 图像生成 · Muse Image 公告

请勿将密钥提交到源代码管理中——可使用下文介绍的 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，并检查是否可以使用这三个 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

对于单次调用，只需在对话中提出要求，Agent 就会传递 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 覆盖。在其中设置这些字段不会产生效果，响应末尾会显示警告，列出被忽略的键。

要更改模型，请使用 model 参数或 MUSE_MODEL，而不是 extra_params。

除了这些核心字段，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。与另外两个工具不同，省略时会得到 webp — 这是 Meta 对此端点设置的默认值
filename_prefix	否	默认值为 muse-iter
model	否	模型 ID；省略则使用服务默认值
extra_params	否	与上文相同的合并和保护规则

此工具没有 n 参数 — /v1/responses 端点每轮返回一张图像。它支持 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" 会返回真正的 PNG（已通过 base64 文件头验证），而非端点默认的 webp。只有 n 确实不可用 — 每轮只能返回一张图像。

scripts/probe-responses-api.mjs 会针对在线 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 字段中，而是在 output[] 中 type === "image_generation_call" 的条目的 result 字段中，采用原始 base64 编码，且没有 data URL 前缀。src/muse-client.ts 中的 extractB64Images 现在可以识别 b64_json（为其他可能的结构保留）和这一已验证的结构。
• 没有 output_format 字段：响应中没有该字段。原先回退使用的默认值 "png" 有误——由于 iterate 请求没有发送 output_format 参数，Meta 使用的默认值与 /images/generations 相同，即 webp。返回的 base64 解码后是有效的 WebP 文件（RIFF/WEBP 标头）。现在回退使用 "webp"。

多轮对话已验证

依次进行了两次真实 API 调用：第一次使用 iterate_image 获取 response_id，第二次使用该 ID 作为 previous_response_id。第二轮只返回了该轮生成的一张图像——没有重新发送第一轮的图像。extractB64Images 的深度遍历逻辑无需更改。

（该次运行中的测试工具没有逐字节捕获第二轮的原始响应，因此这一结论依据的是文件系统证据——恰好有一个输出文件，且没有 -2/-3 后缀——而非逐字节比较。tests/muse-client.test.ts 中新增的固定测试使用的是先前验证过的真实响应结构。）

定价

每张生成的图像收费 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