albertnahas/icogenie-mcp

npm version npm downloads MCP Protocol License: MIT

MCP (Model Context Protocol) server for IcoGenie. Enables AI agents like Claude to generate production-ready SVG icons programmatically.

Installation

npm install -g @icogenie/mcp
# or use directly with npx
npx @icogenie/mcp

Configuration

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "icogenie": {
      "command": "npx",
      "args": ["-y", "@icogenie/mcp"]
    }
  }
}

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:

export ICOGENIE_SESSION_TOKEN="your-session-token"

Available Tools

generate_icon

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_icon

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 }

confirm_regeneration

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_credits

Check your current credit balance.

Cost: Free

check_credits()

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)

download_icon({
  generationId: "abc123",  // or bundleId
  outputPath: "./icons.zip"  // optional, returns base64 if omitted
})

normalize_bundle

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_bundle

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_to_library

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_library

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_from_library

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_daily_credits

Claim 2 free credits, available once every 24 hours.

Cost: Free

claim_daily_credits()

Returns: { credited, creditsRemaining, nextClaimAt }

Example Workflow

1. Check credits:

   check_credits()
   → { credits: 50, team: { name: "Personal" } }
   

2. Generate a single icon:

   generate_icon({ prompt: "notification bell icon", style: "outline" })
   → { sessionId: "abc123", preview: "...", creditsRemaining: 49 }
   

3. 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 }
   

4. Download final package:

   download_icon({ generationId: "abc123", outputPath: "./bell-icon.zip" })
   → { savedTo: "./bell-icon.zip" }
   

Bundle Workflow

1. Plan the bundle (free):

   normalize_bundle({ description: "e-commerce app icons", targetCount: 8 })
   → { icons: [{ name: "cart", ... }, ...], styleRecommendation: "outline" }
   

2. Review and generate (pass bundleId for traceability):

   generate_bundle({ icons: [...], style: "outline", bundleId: "bundle_abc" })
   → { bundleId: "bundle_abc", icons: [...], credits: { previewUsed: 8 } }
   

3. Download bundle:

   download_icon({ bundleId: "xyz789", outputPath: "./ecommerce-icons.zip" })
   

Environment Variables

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

Credit Pricing

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.

When to Use MCP vs CLI vs Web

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

Related

• @icogenie/cli - Command-line interface
• IcoGenie Web - Web application
• AI Agent Docs - Machine-readable documentation
• Developer Docs - Integration guides

License

MIT