muse-image-mcp

# muse-image-mcp

[![CI](https://github.com/kevintsai1202/muse-image-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kevintsai1202/muse-image-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/muse-image-mcp)](https://www.npmjs.com/package/muse-image-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**English** · [繁體中文](docs/README.zh-TW.md) · [简体中文](docs/README.zh-CN.md)

An MCP server that gives any MCP-capable agent — Claude Code, Claude Desktop, Cursor — image generation powered by the Meta Muse image model.

## What it does

Three tools, covering the full loop of working with images in a conversation:

| Tool | What it's for |
|---|---|
| `generate_image` | Text to image. 1–10 images per call. |
| `edit_image` | Edit from reference images — local files or URLs. |
| `iterate_image` | Conversational refinement. Keep saying "make it warmer" and it remembers. |

## Why this server

**Your context window survives.** Every tool writes images to disk and returns an **absolute file path** — never the image bytes. Generating a dozen images costs you a dozen lines of context instead of a dozen megabytes of base64. When you actually want to look at an image, open the path with a file-reading tool.

**Multi-turn refinement without state.** `iterate_image` returns a `response_id`; feed it back as `previous_response_id` and the next turn continues the same conversation. The server itself stores nothing — conversation state lives on Meta's side, so the server stays restartable and stateless.

**New models don't require a new release.** Switch models with `MUSE_MODEL` or a per-call `model` parameter, and pass parameters this server has never heard of through `extra_params`. Fields that determine request structure are protected from being overwritten; everything else is a deliberate escape hatch.

**You always know what it cost.** Every response ends with the estimated cost of that call.

## Requirements

- Node.js >= 20.12.0
- A Meta Muse API key

### Getting an API key

Muse Image runs on the **Meta Model API**, so you register with Meta — not with this project:

1. Go to **<https://dev.meta.ai>** and sign in to the Meta Model API dashboard.
2. Open **API keys**.
3. Click **Create API key** and copy the value.

That value is what you pass as `MUSE_API_KEY` below. Meta's own documentation calls this variab