MCP (Model Context Protocol) server for IcoGenie. Enables AI agents like Claude to generate production-ready SVG icons programmatically.
npm install -g @icogenie/mcp
# or use directly with npx
npx @icogenie/mcpAdd to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"icogenie": {
"command": "npx",
"args": ["-y", "@icogenie/mcp"]
}
}
}The server works automatically when installed globally or via npx.
On first use, the MCP server will:
- Open your browser for authentication
- Ask you to approve access
- Save the session token to
~/.icogenie/config.json
Subsequent uses are automatic - the token is shared with the IcoGenie CLI.
Set ICOGENIE_SESSION_TOKEN environment variable to skip browser authentication:
export ICOGENIE_SESSION_TOKEN="your-session-token"Generate a single icon preview from a text description.
Cost: 1 credit
generate_icon({
prompt: "home icon",
style: "solid", // or "outline"
variations: 1, // 1, 2, or 4
referenceImagePath: "/path/to/reference.png" // optional
})
Returns: { sessionId, preview, previews, creditsRemaining, sessionData, suggestions }
Regenerate a specific icon variation. Returns 4 candidate previews — use confirm_regeneration to finalize your choice (two-phase flow).
Cost: 1 credit
regenerate_icon({
sessionId: "abc123", // for single icons
bundleId: "xyz789", // for bundles (use one or the other)
index: 0, // which variation (0-based)
prompt: "Make it more 3D" // optional refinement
})
Returns: { candidates, regenToken, creditsRemaining }
Finalize a regeneration by selecting one of the 4 candidates.
Cost: Free (included in regenerate_icon)
confirm_regeneration({
regenToken: "tok_abc123",
selectedIndex: 2 // 0-3, which candidate to keep
})
Returns: { success, preview, creditsRemaining }
Check your current credit balance.
Cost: Free
check_credits()
Returns: { credits, team, user }
Download the final SVG + PNG package for an icon or bundle.
Cost: 5 credits (single) or 4 credits/icon (bundle)
download_icon({
generationId: "abc123", // or bundleId
outputPath: "./icons.zip" // optional, returns base64 if omitted
})
Plan an icon bundle by generating an AI-enhanced icon list from a description.
Cost: Free (rate-limited)
normalize_bundle({
description: "food delivery app",
targetCount: 10,
style: "solid"
})
Returns: { bundleId, icons, bundleType, styleRecommendation, reasoning }
Generate a bundle of icons from an icon list.
Cost: 1 credit per icon
generate_bundle({
icons: [
{ name: "home", description: "Home navigation icon" },
{ name: "cart", description: "Shopping cart icon" }
],
style: "solid",
bundleId: "bundle_abc123" // optional, from normalize_bundle
})
Returns: { bundleId, iconCount, icons: [{ name, description, preview }], pricing, creditsUsed, creditsRemaining }
Save a generated icon to your personal library.
Cost: Free
save_to_library({
generationId: "abc123",
name: "notification-bell", // optional display name
tags: ["ui", "alerts"] // optional tags
})
Returns: { success, libraryItemId }
List icons saved in your library.
Cost: Free
list_library({
page: 1, // optional, default 1
limit: 20, // optional, default 20
tag: "ui" // optional filter
})
Returns: { items: [{ id, name, tags, preview, createdAt }], total, page }
Download an icon from your library as SVG + PNG.
Cost: Free
download_from_library({
libraryItemId: "lib_abc123",
outputPath: "./bell-icon.zip" // optional, returns base64 if omitted
})
Returns: { savedTo } or { base64, filename }
Claim 2 free credits, available once every 24 hours.
Cost: Free
claim_daily_credits()
Returns: { credited, creditsRemaining, nextClaimAt }
-
Check credits:
check_credits() → { credits: 50, team: { name: "Personal" } } -
Generate a single icon:
generate_icon({ prompt: "notification bell icon", style: "outline" }) → { sessionId: "abc123", preview: "...", creditsRemaining: 49 } -
Refine if needed (two-phase):
regenerate_icon({ sessionId: "abc123", index: 0, prompt: "Add a dot indicator" }) → { candidates: ["...", "...", "...", "..."], regenToken: "tok_xyz", creditsRemaining: 48 } confirm_regeneration({ regenToken: "tok_xyz", selectedIndex: 1 }) → { success: true, preview: "...", creditsRemaining: 48 } -
Download final package:
download_icon({ generationId: "abc123", outputPath: "./bell-icon.zip" }) → { savedTo: "./bell-icon.zip" }
-
Plan the bundle (free):
normalize_bundle({ description: "e-commerce app icons", targetCount: 8 }) → { icons: [{ name: "cart", ... }, ...], styleRecommendation: "outline" } -
Review and generate (pass bundleId for traceability):
generate_bundle({ icons: [...], style: "outline", bundleId: "bundle_abc" }) → { bundleId: "bundle_abc", icons: [...], credits: { previewUsed: 8 } } -
Download bundle:
download_icon({ bundleId: "xyz789", outputPath: "./ecommerce-icons.zip" })
| Variable | Description | Default |
|---|---|---|
ICOGENIE_API_URL |
API endpoint | https://www.icogenie.xyz |
ICOGENIE_SESSION_TOKEN |
Session token (for CI/CD) | - |
ICOGENIE_CONFIG_DIR |
Config directory | ~/.icogenie |
| Action | Cost |
|---|---|
| Preview (single) | 1 credit |
| Preview (bundle) | 1 credit/icon |
| Download (single) | 5 credits |
| Download (bundle) | 4 credits/icon |
| Regenerate | 1 credit |
| Daily claim | 2 free credits/day |
| Library ops | Free |
Purchase credits at www.icogenie.xyz.
| Use Case | Best Option |
|---|---|
| Generate icons inside Claude/Cursor | MCP |
| Automate in CI/CD pipelines | CLI |
| Quick one-off generation | Web |
| Batch generate icon bundles | CLI or MCP |
| Browse and manage icon library | Web |
- @icogenie/cli - Command-line interface
- IcoGenie Web - Web application
- AI Agent Docs - Machine-readable documentation
- Developer Docs - Integration guides
MIT