imagcon-mcp

# imagcon-mcp

Local MCP server that wraps the [Imagcon](https://imagcon.app) API so assistants can generate PWA icon sets (all sizes, maskable assets, `manifest.json`) and iOS splash screens without opening the site. Runs as a stdio process via `uvx` — no hosted service dependency, no persistent connections.

## Requirements

- Python 3.11–3.12
- [uv](https://docs.astral.sh/uv/) (provides `uvx`)
- An Imagcon API key starting with `ic_live_` from [imagcon.app/api-keys](https://imagcon.app/api-keys)

## Install

The package is self-hosted (not on PyPI). Install directly from the wheel:

```bash
claude mcp add imagcon -- uvx --from https://imagcon.app/downloads/imagcon_mcp-0.2.5-py3-none-any.whl imagcon-mcp --api-key ic_live_...
```

Or with the key in the environment instead of on the command line:

```bash
claude mcp add imagcon -- uvx --from https://imagcon.app/downloads/imagcon_mcp-0.2.5-py3-none-any.whl imagcon-mcp
```

```bash
export IMAGCON_API_KEY=ic_live_...
```

For other MCP clients (Cursor, Windsurf, VS Code, Cline, Zed, Warp, Continue.dev), use the equivalent stdio config:

```json
{
  "mcpServers": {
    "imagcon": {
      "command": "uvx",
      "args": ["--from", "https://imagcon.app/downloads/imagcon_mcp-0.2.5-py3-none-any.whl", "imagcon-mcp", "--api-key", "ic_live_..."]
    }
  }
}
```

Per-client config file locations and full examples: see CLIENT-CONFIGS in [imagcon.app/.well-known/blueprint.txt](https://imagcon.app/.well-known/blueprint.txt).

## Tools

**Images**

- **`generate_image`** — AI-generate a source image from a text description. Returns `image_key` and a preview URL. Show the preview to the user and confirm before generating icons.
- **`save_image`** — Save a generated image to your gallery by `image_key` and `name`.
- **`list_saved_images`** — List all saved source images with keys and preview URLs.
- **`create_icons_from_key`** — Generate a full PWA icon set from an already-saved `image_key` — no re-generation, no upload. Same output as `generate_pwa_icons`.

**Icon sets**

- **`generate_pwa_icons`** — AI-generate a source image, then resize to all PWA sizes, save the set, download the ZIP, extract to `output_dir` (default `./public/icons`).
- **`create_pwa_icons_from_image`** — Same PWA pipeline from an existing local PNG/JPEG/WebP at `image_path` (no AI generation).
- **`list_saved_icon_sets`** — List saved icon sets with IDs.
- **`download_icon_set`** — Download a saved icon set ZIP by `set_id`, extract to `output_dir`.
- **`get_icon_set_download_url`** — Get an authenticated download URL for a saved icon set ZIP by `set_id`.

**Splash screens**

- **`generate_splash_screens`** — AI-generate a source image and produce 16 iOS splash screens, extract to `output_dir` (default `./public/splash`).
- **`create_splash_screens_from_image`** — Same splash pipeline from an existing local PNG/JPEG/WebP at `image_path` (no AI generation).
- **`create_splash_screens_from_key`** — Same splash pipeline from an existing `image_key` (e.g. from `generate_image` or `list_saved_images`) — composites the icon on each canvas size without re-generating.
- **`download_splash_screens`** — Download a saved splash screen set ZIP by `set_id`, extract to `output_dir`.
- **`get_splash_screen_download_url`** — Get an authenticated download URL for a saved splash screen set ZIP by `set_id`.

**Account**

- **`get_credit_balance`** — Returns remaining Imagcon credits.
- **`setup_wallet_profile`** — Activate a permanent Imagcon account after a pay-per-call x402 payment. Pass wallet address, profile token from `X-Imagcon-Token`, name, `terms_confirmed` (after reading https://imagcon.app/terms-of-service), and a wallet signature over `imagcon.app/profile/activate:{profile_token}:{unix_timestamp}`.

AI image generation (`generate_image`, `generate_pwa_icons`, `generate_splash_screens`) and icon/splash set exports use credits. `create_pwa_icons_from_image`, `create_splash_screens_from_image`, `create_splash_screens_from_key`, and `create_icons_from_key` skip AI generation credits but still charge for export.

## Configuration

| Source | Variable / flag |
|--------|------------------|
| Environment | `IMAGCON_API_KEY` |
| CLI | `--api-key` (overrides the env var) |

If the key is missing, the process exits with an error pointing to [imagcon.app/api-keys](https://imagcon.app/api-keys).

## API base URL

All requests go to `https://imagcon.app` (no other base URL is supported).