unsquared-mcp

The Unsquared team's shared MCP server. Exposes AI-callable image tools over stdio so any MCP client (Claude Code, Cursor, Claude Desktop, etc.) can use them.

Tools:

• generate_image — text-to-image with OpenAI's gpt-image-2, optional in-pipeline background removal.
• edit_image — image-to-image with one or more reference images, optional mask for inpainting, optional background removal.
• remove_background — rembg-based background removal for any image on disk.

The AI decides where to save output. Pass output_path for "save this into my project", omit it for "just show me the image, don't touch my disk".

Install

Requires Node 22+. For background removal, also install rembg:

uv tool install "rembg[cpu,cli]"
# or
pipx install "rembg[cpu,cli]"

generate_image and edit_image work without it. Only the bg-removal path needs it.

MCP client setup

Claude Code

claude mcp add unsquared --scope user --env OPENAI_API_KEY=sk-... -- npx -y unsquared-mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "unsquared": {
      "command": "npx",
      "args": ["-y", "unsquared-mcp"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

Fully quit Claude Desktop (⌘Q) and relaunch.

Cursor

Same JSON in ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project).

Environment variables

Only OPENAI_API_KEY is commonly set. Everything else is optional.

| Var | Default | Purpose | |---|---|---| | OPENAI_API_KEY | — | Required for generate_image and edit_image. Not needed for remove_background. | | REMBG_MODEL | birefnet-general | Default rembg model when remove_background=true (per-call override via model on remove_background). | | REMBG_SIDECAR_PORT | 0 (auto) | Port for the lazy-spawned rembg HTTP sidecar. |

output_path semantics (all tools)

| output_path | Behavior | |---|---| | omitted | Image returned inline only. Not saved to disk. | | Absolute file path with .png / .webp / .jpg / .jpeg | Saved to that exact file. Extension wins over output_format. Multi-image runs get -1, -2, ... suffixes. | | Absolute directory path | Saved inside with an auto-generated filename. output_format determines the extension. | | Relative path | Error — must be absolute. |

Every tool call returns the full image inline regardless of whether it was saved, so the AI can see exactly what was produced.

Tools

generate_image

| Param | Type | Default | Notes | |---|---|---|---| | prompt | string (1-32000) | — | Required. | | output_path | string (abs) | — | See table above. | | size | "1024x1024" | "1536x1024" | "1024x1536" | "auto" | "auto" | | | quality | "low" | "medium" | "high" | "medium" | | | output_format | "png" | "webp" | "jpeg" | "png" | Only used when output_path is a directory or omitted. | | n | int 1-4 | 1 | | | remove_background | boolean | false | Final format must support alpha (png/webp). |

edit_image

| Param | Type | Default | Notes | |---|---|---|---| | prompt | string | — | Required. What to do with the references. | | image_paths | string[] (abs) | — | 1-10 references. Multi = composition/blend. | | mask_path | string (abs) | — | Optional. Transparent pixels = regions to repaint (inpainting). Only valid with a single image_paths entry. | | output_path | string (abs) | — | See table above. | | size, quality, output_format, n, remove_background | | | Same as generate_image. |

remove_background

| Param | Type | Default | Notes | |---|---|---|---| | input_path | string (abs) | — | Required. | | output_path | string (abs) | — | See table above. Must resolve to a PNG (rembg output is always PNG with alpha). | | model | string | $REMBG_MODEL | bria-rmbg, birefnet-portrait, u2net_human_seg, etc. |

Development

pnpm install
pnpm build
pnpm test

Publishing

Tag a release (git tag v0.2.0 && git push --tags) and the workflow in .github/workflows/publish.yml runs npm publish. Needs NPM_TOKEN in repo secrets with "Bypass 2FA for publishing" enabled.

License

MIT.