IcoGenie MCP Server

@icogenie/mcp

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. **Chec