Content
# 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.4-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.4-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.4-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).
- **`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.
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`, 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).
