albertnahas/icogenie-mcp

MCP (Model Context Protocol) server for IcoGenie. Enables AI agents like Claude to generate production-ready SVG icons programmatically.
Installation
Configuration
Claude Desktop
Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
Claude Code
The server works automatically when installed globally or via npx.
Authentication
On first use, the MCP server will:
1. Open your browser for authentication
2. Ask you to approve access
3. Save the session token to ~/.icogenie/config.json
Subsequent uses are automatic - the token is shared with the IcoGenie CLI.
CI/CD Environments
Set ICOGENIE_SESSION_TOKEN environment variable to skip browser authentication:
Available Tools
generate_icon
Generate a single icon preview from a text description.
**Cost:** 1 credit
**Returns:** { sessionId, preview, previews, creditsRemaining, sessionData, suggestions }
regenerate_icon
Regenerate a specific icon variation. Returns 4 candidate previews — use confirm_regeneration to finalize your choice (two-phase flow).
**Cost:** 1 credit
**Returns:** { candidates, regenToken, creditsRemaining }
confirm_regeneration
Finalize a regeneration by selecting one of the 4 candidates.
**Cost:** Free (included in regenerate_icon)
**Returns:** { success, preview, creditsRemaining }
check_credits
Check your current credit balance.
**Cost:** Free
**Returns:** { credits, team, user }
download_icon
Download the final SVG + PNG package for an icon or bundle.
**Cost:** 5 credits (single) or 4 credits/icon (bundle)
normalize_bundle
Plan an icon bundle by generating an AI-enhanced icon list from a description.
**Cost:** Free (rate-limited)
**Returns:** { bundleId, icons, bundleType, styleRecommendation, reasoning }
generate_bundle
Generate a bundle of icons from an icon list.
**Cost:** 1 credit per icon
**Returns:** { bundleId, iconCount, icons: [{ name, description, preview }], pricing, creditsUsed, creditsRemaining }
save_to_library
Save a generated icon to your personal library.
**Cost:** Free
**Returns:** { success, libraryItemId }
list_library
List icons saved in your library.
**Cost:** Free
**Returns:** { items: [{ id, name, tags, preview, createdAt }], total, page }
download_from_library
Download an icon from your library as SVG + PNG.
**Cost:** Free
**Returns:** { savedTo } or { base64, filename }
claim_daily_credits
Claim 2 free credits, available once every 24 hours.
**Cost:** Free
**Returns:** { credited, creditsRemaining, nextClaimAt }
Example Workflow
1. **Check credits:**
2. **Generate a single icon:**
3. **Refine if needed (two-phase):**
4. **Download final package:**
Bundle Workflow
1. **Plan the bundle (free):**
2. **Review and generate (pass bundleId for traceability):**
3. **Download bundle:**
Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|