Superdesign MCP Server

Superdesign MCP Server

An MCP (Model Context Protocol) server that brings Superdesign - an open source AI design agent by @jasonzhou1993 and @jackjack_eth - to Claude Code as native tools. This server operates as a "design orchestrator" that provides structured specifications for your IDE's LLM to execute, enabling Superdesign's sophisticated design capabilities without requiring Anthropic API keys.

Key Benefits

• No API Keys Required: Works directly with Claude Code's built-in LLM connection
• Local Execution: Runs entirely on your machine as an MCP server
• IDE Integration: Seamlessly integrates with Claude Code (and potentially Cursor, Windsurf, or other MCP-compatible IDEs - untested)
• Based on Open Source: Built on top of Superdesign.dev, an open source AI design system

Installation

1. Install dependencies:

npm install

2. Build the server:

npm run build

Claude Code Integration

1. Add the MCP server to your Claude Code configuration:

# Create or edit your Claude Code MCP settings file
# On macOS:
mkdir -p ~/.claude-code
cp claude-mcp-config.json ~/.claude-code/mcp-settings.json

# Or add manually to your existing mcp-settings.json:

Example ~/.claude-code/mcp-settings.json:

{
  "mcpServers": {
    "superdesign": {
      "command": "node",
      "args": ["/path/to/superdesign/dist/index.js"],
      "env": {}
    }
  }
}

2. Restart Claude Code

3. The MCP server will provide these Superdesign orchestrator tools in Claude Code:

   • superdesign_generate - Returns specifications for Claude to generate designs
   • superdesign_iterate - Returns instructions for Claude to iterate on existing designs
   • superdesign_extract_system - Returns instructions for design system extraction
   • superdesign_list - Lists all created designs in the workspace

Development

Run in development mode:

npm run dev

Superdesign Tools Available

superdesign_generate

Returns structured specifications for Claude Code to generate designs:

• UI designs: Complete responsive interfaces
• Wireframes: Minimal black and white layouts
• Components: Individual UI components (HTML/React/Vue)
• Logos: SVG logo designs
• Icons: SVG icon designs

Parameters:

• prompt: Description of what to create
• design_type: Type of design (ui, wireframe, component, logo, icon)
• variations: Number of variations to generate (1-5, default 3)
• framework: Framework for components (html, react, vue)

Output: Detailed specifications including Superdesign system prompt, file naming patterns, and design guidelines for Claude Code to execute.

superdesign_iterate

Returns iteration instructions for Claude Code to improve existing designs:

• Reads existing design files
• Provides structured feedback application guidelines
• Maintains design consistency through Superdesign principles

Parameters:

• design_file: Path to existing design file
• feedback: Improvement instructions
• variations: Number of variations to create

Output: Iteration specifications including original design content, feedback to apply, and Superdesign guidelines for Claude Code to execute.

superdesign_extract_system

Returns instructions for Claude Code to extract design systems from screenshots:

• Provides analysis framework for visual design patterns
• Guides extraction of color palettes, typography, spacing
• Specifies JSON structure for reusable design systems

Output: Extraction specifications and JSON schema for Claude Code to analyze images and create design system files.

superdesign_list

List all Superdesign creations in workspace:

• Shows design iterations
• Shows extracted design systems
• Displays file organization

superdesign_gallery

Generate an interactive HTML gallery to view all designs:

• Browser-based gallery - opens in your default browser
• Visual previews - see design thumbnails in a responsive grid
• Interactive features - click to view full-screen, copy paths
• Mobile responsive - works on desktop, tablet, and mobile
• Auto-discovery - finds all HTML/SVG files in design_iterations/

Parameters:

• workspace_path: Workspace directory (optional, defaults to current directory)

Output: Gallery HTML file with embedded previews and JavaScript interactions. The gallery opens automatically in your browser, providing a Superdesign-like canvas experience.

How the Orchestrator Works

This MCP server operates as a design orchestrator rather than a direct generator:

1. User Request: "Generate a modern dashboard UI"
2. MCP Server: Returns detailed specifications with:
   • Complete Superdesign system prompt and guidelines
   • Exact file paths and naming conventions
   • Design type-specific instructions
   • Number of variations to create
3. Claude Code: Receives specifications and:
   • Generates the actual HTML/SVG/React code
   • Saves files to specified locations
   • Follows all Superdesign design principles

Usage in Claude Code

Once configured, you can use Superdesign through Claude Code with natural language:

Example Usage:

• "Generate a modern dashboard UI design"
• "Create 3 variations of a login page wireframe"
• "Design a React component for a product card"
• "Make a minimalist logo for a tech startup"
• "Iterate on the dashboard design with better spacing"
• "Show me the gallery of all my designs"

Requirements:

• Claude Code with MCP support
• No API keys needed (uses Claude Code's existing LLM connection)

File Organization:Designs are automatically saved to superdesign/ directory (visible folder):

• design_iterations/ - Generated designs (HTML/SVG files)
• design_system/ - Extracted design systems (JSON files)

Benefits:

• No API key configuration required
• Uses Claude Code's existing LLM capabilities
• Maintains all of Superdesign's sophisticated design methodology
• Proper file organization and naming conventions
• Full design iteration workflow support

Known Issues & Troubleshooting

File Permissions Error

If you encounter permission errors when running the MCP server:

# Add execute permissions to the built file
chmod +x dist/index.js

MCP Tools Not Appearing

If Superdesign tools don't appear in Claude Code after installation:

1. Ensure you've completely quit Claude Code (not just closed the window)
2. Restart Claude Code from your terminal
3. Verify the server is registered: claude mcp list
4. Check the tools are available by asking Claude: "What tools do you have available?"

Server Registration Issues

If the server fails to register:

# Remove and re-add the server
claude mcp remove superdesign -s user
claude mcp add --scope user superdesign /path/to/superdesign/dist/index.js

Build Errors

Ensure you have Node.js 16+ installed:

node --version  # Should be v16.0.0 or higher

🤝 Relationship to Superdesign

This MCP server provides a complementary integration for Superdesign by @jasonzhou1993 and @jackjack_eth.

While Superdesign offers an IDE extension that works across multiple editors, this MCP server specifically enhances Claude Code by:

• Eliminating the need for API keys - uses Claude Code's built-in LLM connection
• Providing native tool integration - no manual prompt copying required
• Enabling direct tool calls - seamless workflow without copy/paste

This addresses the community request for Claude Code API provider support (see Superdesign Issue #3).

How it's Different

License

This project follows the same license as the original Superdesign project. Please refer to the Superdesign repository for license details.