mcp-stability-ai

A Claude MCP server for Stability.ai image generation and editing — always maintained and up to date with the v2beta API.

Generate, edit, upscale, and manage images entirely through natural language inside Claude. No manual file paths required.

Why this exists

I built this because I needed a maintained Claude Desktop MCP workflow for Stability.ai image generation/editing, local file handling, and occasional cover/product-shot work without owning a capable GPU or maintaining a local ComfyUI stack. This is not meant to replace local-first tools like ComfyUI or Automatic1111. It is an open-source integration for users who specifically want Claude Desktop + MCP + Stability.ai in one conversational workflow.

Tools

Generation

| Tool | Description | Cost | |---|---|---| | generate_image_sd3 | SD3.5 — best overall quality, supports negative prompts | ~$0.035–$0.065 | | generate_image_core | Core — fast generation with style presets | ~$0.03 | | generate_image_ultra | Ultra — highest photorealistic quality | ~$0.08 |

Editing

| Tool | Description | Cost | |---|---|---| | remove_background | Remove background, returns transparent PNG | $0.02 | | replace_background | Replace + relight background — great for product shots | ~$0.04 | | inpaint | Edit a masked region using a prompt | ~$0.03 | | search_and_replace | Find an object by description and replace it, no mask needed | $0.04 | | search_and_recolor | Recolor a specific object by description, no mask needed | ~$0.04 | | outpaint | Extend the canvas in any direction | $0.04 |

Upscaling

| Tool | Description | Cost | |---|---|---| | upscale_fast | 4x upscale, preserves original appearance | $0.01 | | upscale_creative | 4x upscale with AI artistic enhancement | ~$0.25 |

File management (no API cost)

| Tool | Description | |---|---| | list_images | List images in output/input directories with sizes and dates | | use_clipboard_image | Save clipboard image to file for use in the next tool (macOS) | | reveal_in_finder | Open the output folder or reveal a file in Finder (macOS) | | delete_image | Permanently delete an image file |

Installation

1. Get a Stability API key

2. Add the server to Claude Desktop

Open the Claude Desktop config file and add the stability block inside mcpServers:

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json
Linux — ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stability": {
      "command": "npx",
      "args": ["-y", "mcp-stability-ai"],
      "env": {
        "STABILITY_API_KEY": "sk-YOUR_KEY_HERE"
      }
    }
  }
}

3. Restart Claude Desktop

The Stability AI tools will appear automatically.

Usage examples

Generate an image

"Generate a cinematic photo of a red panda on a mossy log in a rainy forest, 16:9"

Product photo pipeline (remove → replace → upscale)

"Take the photo at /Users/me/dragon.jpg, remove the background, place it on a dark dramatic studio background with top lighting, then upscale 4x."

Claude chains the tools automatically:

remove_background → isolates subject, saves PNG
replace_background → dark studio background + relighting
upscale_fast → 4x resolution boost

Use the clipboard instead of a file path

"Use the image I just copied, remove the background, then replace it with a blurred workshop background."

Copy an image to clipboard (⌘C in any app)
Claude calls use_clipboard_image → saves to file
remove_background → replace_background automatically

Work with short filenames

After the first tool runs, Claude knows the output filename. You can reference files naturally:

"Now upscale the remove_background result" or "List my images and upscale the latest one"

list_images shows all available files — Claude can pick the right one without you typing a path.

Recolor an object

"In /Users/me/device.jpg, recolor the plastic housing to matte black."

Extend a portrait to widescreen

"Outpaint /Users/me/portrait.jpg by 600px left and 600px right, prompt: continuation of the blurred background."

Output files

Results are saved to ~/Downloads/stability-ai/ by default (created automatically).

Filename format: {tool}_{YYYY-MM-DD}_{HH-MM-SS}_{seed}.{ext}
Example: replace-background_2026-06-09_11-36-20_2847291838.png

Environment variables

| Variable | Default | Description | |---|---|---| | STABILITY_API_KEY | (required) | Your Stability AI API key | | STABILITY_OUTPUT_DIR | ~/Downloads/stability-ai | Where generated images are saved | | STABILITY_INPUT_DIR | (unset) | Folder Claude searches for input images by short name |

Configure in Claude Desktop:

"env": {
  "STABILITY_API_KEY": "sk-...",
  "STABILITY_OUTPUT_DIR": "/Users/you/Pictures/stability",
  "STABILITY_INPUT_DIR": "/Users/you/Pictures/input"
}

With STABILITY_INPUT_DIR set, you can pass bare filenames like "dragon.jpg" instead of full paths — Claude resolves them automatically.

Development

git clone https://github.com/alesurli/mcp-stability-ai.git
cd mcp-stability-ai
npm install
npm run build

Point Claude Desktop at your local build:

{
  "mcpServers": {
    "stability": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-stability-ai/dist/index.js"],
      "env": {
        "STABILITY_API_KEY": "sk-YOUR_KEY_HERE"
      }
    }
  }
}

Requires Node.js 22+.

Contributing

See CONTRIBUTING.md.

License

MIT

MCP Servers