# MCP server MooshieUI can run a [Model Context Protocol](https://modelcontextprotocol.io) server so AI assistants (Claude Code, Claude Desktop, Cursor, LM Studio, chat bots and others) can generate, edit and upscale images (local models and NovelAI) and make music, use your saved characters, styles, chunks and wildcards, check the queue, search the gallery and your Eagle library, and download full-size images. It is **off by default**. Turn it on in **Settings > AI assistants (MCP)**. ## How it works - Listens on `http://127.0.0.1:3210/mcp` (the port is configurable). It never listens on the network, even with LAN mode on. Cloud apps reach it only through a tunnel you turn on (see [Cloud apps](#cloud-apps-claude-custom-connectors-chatgpt)). - Runs in every mode: desktop window, browser mode and the headless server. In Docker, `127.0.0.1` is the container itself, so it is only reachable from inside the container. - Every request needs `Authorization: Bearer `, or the token in the path for apps that take only a URL: `POST /mcp/`. The token is generated when the server is first enabled and can be replaced from Settings. Requests with a non-local `Host` or `Origin` header are refused (except your own public address, below), so a web page can't reach it. - Transport: Streamable HTTP with plain JSON responses (protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05). No server-initiated stream, so `GET /mcp` answers 405. - Settings are kept in `mcp.json` in the app data folder, not in `config.json`. ## Generation setups The frontend works out a model's family, loaders, text encoder and tuned defaults before every generation, and that can't be rebuilt from a filename on the backend. So the MCP server reuses what already works: each time the owner runs a generation, MooshieUI saves that request as the model's **setup** (in `mcp_setups.json`, without the prompt and without any input image). `generate_image` starts from a setup and changes only what the assistant asks for. Three kinds of run make a setup, one per model each: - **txt2img on a local model.** Used by `generate_image`. - **txt2img on NovelAI**, keyed by the NovelAI model id (`nai-diffusion-4-5-full`, `nai-diffusion-5-full`, ...). It keeps the quality tags, UC preset, sampler, effort and the local post-process, and drops the character prompts, vibes and precise references (they belong to one image, and a vibe costs Anlas to encode). - **Image Edit on a local model.** A Krea 2 setup keeps its edit recipe (Identity Edit, General Edit or Style Reference) and its fidelity settings, and uses the first two images. A model is usable over MCP once it has been used for one such run in MooshieUI. `generate_image` with `source_image` (img2img) and `upscale_image` reuse the txt2img setup; `edit_image` needs an Image Edit one. NovelAI img2img, inpainting and upscale, local img2img and inpainting, and video runs don't create setups. Prompts are kept out of a setup, including the Moody Moss face and area detail prompts. Images generated over MCP are saved to the owner's gallery (with normal metadata, `mooshie_source: mcp`) and show up in an open MooshieUI window right away. ### NovelAI costs nothing over MCP An assistant can't spend Anlas. A NovelAI request over MCP must fit the Opus free window (one image, at most 1 megapixel such as 832x1216 or 1024x1024, at most 28 steps), the key in Settings must be on Opus (checked every 10 minutes), the face pass is held to free crops, and setups never carry vibes. Anything else is refused with a message saying why. NovelAI runs one request at a time per account, so MCP jobs wait their turn behind the Generate page's. The key used is the one active in Settings. ## Prompts: wildcards, characters, styles and chunks `generate_image` prompts work like the Generate page's: - `__name__` picks a line from a wildcard file in the wildcards folder (`.txt`, `.yaml`, `.json`, folders as `__folder/name__`, `*` globs), and `{a|b|c}` picks one choice (`{2$$a|b|c}`, weights `{3::a|b}` and nesting work too). Both are seeded by the job's seed, so a fixed seed repeats its picks. Wildcards set to "in order" in the editor pick at random over MCP, since their counters live in the window. Names that match no file are left in the prompt and listed in the result as `unknown_wildcards`. - `characters` adds saved characters by name, picking the card saved for the model's family (else one written the same way, tags or sentences). On NovelAI V4 and later each becomes its own character prompt with its UC in that box; elsewhere its prompt goes at the end of the prompt and its UC into the negative prompt. - `styles` appends a saved artist style's weighted artist tags and adds its UC. - `chunks` adds saved prompt chunks: `prepend`, `append` or `random` (one random line). The default is the mode the chunk is active with in MooshieUI, else `append`. Their UC is added too. - `use_active_styles: true` also adds the styles and chunks that are active in MooshieUI right now. `list_library` lists all four, and `get_character` returns a character's full card, memory files and portrait. The library is read from the owner's synced data and can't be changed over MCP. ## Working from an existing image Tools that take an image accept a gallery filename or the picture itself as base64 or a data URL (for one the assistant got elsewhere, such as a chat). Every input is decoded and re-encoded as a plain PNG before ComfyUI or NovelAI sees it, up to 8192 px a side and 25 MB. - `generate_image` with `source_image` runs img2img (`denoise`, default 0.6). The size follows the source's aspect ratio at the setup's pixel count unless `width`/`height` are given. On NovelAI this is NovelAI img2img, still inside the free window. - `generate_image` with `reference_images` (one or two) turns on the model's style reference: the Anima Reference Adapter, Flux Redux or IP-Adapter, with the setup's reference settings. When the owner's Anima setup uses SnapRef, it takes up to 8 images of the same character instead, at strength 1. Local models only. - `edit_image` edits the first image with an instruction on an Image Edit model; more images are references. - On a Ming-Image Layer setup, `edit_image` splits the image into transparent layers instead, one result per layer; the instruction names the count ("Decompose this image into 5 layers", default 4). - `upscale_image` runs Refine: upscales by `scale` (1 to 4) and refines with the local model that made the image (or the one given), guided by the image's own prompt. ## Download links Results that name an image carry a `url` that downloads the full-size file from the MooshieUI machine: `generate_image`, `edit_image`, `upscale_image`, `get_job`, `search_gallery`, `get_image`, and Eagle items in `search_eagle` and `get_eagle_image`. A chat bot can post the link or fetch the file. JPEG XL files are sent as PNG; other formats as they are, metadata included. - Over the tunnel or your own address the link uses that public address; for apps on this machine it is `http://127.0.0.1:`. - A link is signed for that one file and expires after `link_hours` (default 24, at most 168). The signature is derived from the MCP token without revealing it, and **New token** in Settings voids every link handed out before. - Anyone holding a link can download that file until it expires. ## Boards and Eagle `list_boards` lists the gallery boards, and `search_gallery` filters by `board`, `favourites_only` and `min_rating`; results say each image's board, favourite and rating. Boards are read from the owner's synced data and can't be changed over MCP. With [Eagle](https://eagle.cool) open on the MooshieUI machine, `search_eagle` searches its library by keyword, tags and folder (`list_folders: true` lists folders), `get_eagle_image` shows an item, and `send_to_eagle` adds gallery images the same way the gallery's Eagle export does (to the folder set in Settings, or `folder`). ## Music `generate_music` uses the same YuE2 backend as the Music page. It needs no setup: the backend builds the YuE2 graph itself from the style, lyrics, length and seed, with the Music page's defaults (full planning, 32 steps, 120 seconds). `list_models` with `category: music` says whether YuE2 is installed and lists its checkpoints. Finished songs are copied out of ComfyUI into the `music` folder in the app data folder, as `mcp__