Aicon

MCP Server + API for intelligent icon management with AI-powered generation and web-based authentication.

🚀 Quick Start

For Users

# 1. Install the MCP server
npm install -g aicon-mcp

# 2. Add to Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "aicon": {
      "command": "aicon",
      "args": []
    }
  }
}

# 3. Authenticate in Claude Desktop
# Use: login({action: "login"}) to start web authentication

For Developers/Admins

See DEPLOY.md for complete deployment instructions.

---

📋 What This Does

• 🔍 Search Icons: Find from 275,000+ existing icons (Material, Heroicons, Lucide, etc.)
• 🎨 Generate Icons: Create custom icons using AI (powered by Runware.ai)
• 📥 Download Icons: Save as SVG or PNG with background removal
• 🔐 Web Authentication: Claude Code-style login flow with subscription plans
• 📊 Usage Tracking: Monitor API usage and rate limits
• 🔑 Secure: API key authentication with permission controls

---

🔐 Authentication System

Web-Based Login Flow

1. Run login({action: "login"}) in Claude Desktop
2. Browser opens automatically for authentication
3. Login/register with credentials
4. Select subscription plan (Free/Pro/Enterprise)
5. API key generated and saved automatically
6. All icon tools now available!

Subscription Plans

• 🆓 FREE: 100 searches/month, SVG downloads
• 🚀 PRO: Unlimited searches + AI generation ($9/month)
• 🏢 ENTERPRISE: Everything unlimited + API access ($29/month)

---

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Server    │───▶│   Backend API   │───▶│   External APIs │
│   (Local)       │    │   (Vercel)      │    │ Iconify+Runware │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                        │                        │
        ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Claude Desktop  │    │   Supabase DB   │    │  Generated SVGs │
│   (AI Client)   │    │ (Usage & Keys)  │    │   (./Aicon/)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

---

📦 Components

1. MCP Server (/src/)

• Tools: 6 MCP tools including web authentication
• Config: Multi-level configuration (env, user, project)
• Storage: Local file management for downloaded icons
• Client: HTTP client with request tracking

2. Backend API (Deployed to Vercel)

• Endpoints: REST API for icon search, generation, usage
• Auth: Production API key system with permissions
• Database: Supabase integration for usage tracking
• Processing: Image manipulation (Sharp, Potrace)

---

🛠️ Development

MCP Server

npm install
npm run dev        # Development mode
npm run build      # Build TypeScript
npm run typecheck  # Type checking

---

🎯 Usage Examples

Authenticate First

// Start web authentication in Claude Desktop
login({action: "login"})

// Check authentication status
login({action: "status"})

// View subscription plans
login({action: "plans"})

Search for Icons

// Search icons after authentication
search_icons({
  query: "home",
  library: "heroicons", 
  style: "outline"
})

Generate Custom Icons

// Generate AI icons (Pro/Enterprise plans)
generate_icons({
  subject: "rocket ship",
  context: "space app",
  style: "filled",
  colors: "blue gradient"
})

Download Icons

// Download icons in various formats
fetch_icons({
  id: "heroicons:home",
  type: "iconify",
  format: "svg"
})

---

📊 Features

• ✅ 275,000+ Icons from 200+ open source icon libraries
• ✅ AI Generation with background removal
• ✅ Web Authentication Claude Code-style login flow
• ✅ Subscription Plans Free/Pro/Enterprise tiers
• ✅ Format Support (SVG, PNG)
• ✅ Rate Limiting with usage tracking
• ✅ Production Ready with comprehensive tests
• ✅ Claude Integration via MCP protocol

---

📄 License

MIT License - see LICENSE file for details.