MCP Tailwind Gemini Server

Advanced Model Context Protocol (MCP) server for Tailwind CSS with Gemini AI integration and cross-platform support for intelligent design assistance across all major development environments.

🌟 Features

🤖 AI-Powered Design

Intelligent Component Generation: Create sophisticated Tailwind components using Gemini AI
Smart Optimization: AI-driven class optimization and conflict resolution
Design Analysis: Comprehensive design quality assessment with improvement suggestions
Theme Creation: Generate cohesive design systems with AI assistance

🎨 Tailwind CSS Tools

Component Generator: Create buttons, cards, forms, navigation, modals, and custom components
Class Optimizer: Clean up redundant classes and resolve conflicts
CSS Converter: Transform existing CSS/SCSS to Tailwind classes
Layout Generator: Build responsive layouts for dashboards, landing pages, blogs, and more
Theme Creator: Generate custom color palettes, typography, and design tokens
Preview Generator: Visual component previews with screenshot capability

🌐 Cross-Platform Integration

Multi-Framework Support: React, Vue, Svelte, Angular with automatic component conversion
Build Tool Integration: Vite, Webpack, Next.js, Nuxt, SvelteKit project generation
IDE Extensions: VS Code, WebStorm plugins with live assistance
Design Tool Sync: Figma plugin for design-to-code conversion
Universal Deployment: CLI tools, browser extensions, and API integrations

🚀 Advanced Capabilities

Framework Adapters: Automatic component conversion between frameworks
Universal Project Generation: Create full-stack applications with any tech stack
Multi-Platform Deployment: Deploy to development environments, production, and design tools
External API Integration: Gemini, OpenAI, Claude, Figma for enhanced AI capabilities
Responsive Design: Mobile-first approach with breakpoint optimization
Accessibility: WCAG compliance checking and enhancement suggestions
Performance: Bundle size optimization and render performance analysis
Visual Preview: Screenshot generation for component visualization

📦 Installation

Prerequisites

Node.js 18 or higher
npm or yarn package manager
Docker (for containerized deployment)
(Optional) Gemini API key for AI features

Quick Start with Docker

Clone the repository:

git clone https://github.com/Tai-DT/mcp-tailwind-gemini.git
cd mcp-tailwind-gemini

Set up environment:

# Copy environment template
cp env.example .env

# Edit .env file with your API key
# GEMINI_API_KEY=your_actual_api_key_here

Deploy with Docker:

# Build and run production container
docker-compose -f docker-compose.prod.yml up -d

# Check status
docker ps | grep mcp-tailwind-server

Local Development Setup

Install dependencies:

npm install

Build the project:

npm run build

Set up environment:

# Copy environment template
cp env.example .env

# Edit with your API key
# GEMINI_API_KEY=your_actual_api_key_here

Run development server:

npm run dev

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tailwind-gemini": {
      "command": "npx",
      "args": ["mcp-gemini-cli", "--allow-npx"],
      "env": {
        "GEMINI_API_KEY": ""your-api-key-here"
      }
}

Config File Locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Alternative Configuration (using npm):

{
  "mcpServers": {
    "mcp-tailwind-gemini": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/path/to/your/mcp-tailwind-gemini",
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

For Cursor IDE

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-tailwind-gemini": {
      "command": "node",
      "args": ["/path/to/your/mcp-tailwind-gemini/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

🛠️ Available Tools

Component Generation

{
  "tool": "generate_component",
  "description": "Create a responsive button component",
  "type": "button",
  "variant": "primary",
  "size": "lg",
  "framework": "react",
  "responsive": true,
  "accessibility": true
}

Class Optimization

{
  "tool": "optimize_classes", 
  "html": "<div class=\"p-4 px-4 py-4 text-blue-500 text-blue-600\">Content</div>",
  "removeRedundant": true,
  "mergeConflicts": true
}

Theme Creation

{
  "tool": "create_theme",
  "brandColor": "#3B82F6",
  "style": "modern",
  "colorCount": 9,
  "includeConfig": true
}

Design Analysis

{
  "tool": "analyze_design",
  "html": "<div>...</div>",
  "checkAccessibility": true,
  "checkResponsive": true,
  "checkPerformance": true
}

Preview Generation

{
  "tool": "generate_preview",
  "html": "<button class=\"bg-blue-500 text-white px-4 py-2 rounded\">Button</button>",
  "width": 800,
  "height": 600
}

CSS Conversion

{
  "tool": "convert_to_tailwind",
  "code": ".button { padding: 1rem; background: #3B82F6; }",
  "format": "css",
  "optimize": true
}

AI Suggestions

{
  "tool": "suggest_improvements",
  "html": "<div>...</div>",
  "context": "E-commerce product card",
  "focusAreas": ["accessibility", "performance", "ux"]
}

Layout Generation

{
  "tool": "create_layout",
  "type": "dashboard",
  "sections": ["header", "sidebar", "main", "footer"],
  "complexity": "medium",
  "framework": "react"
}

🎯 Use Cases

Creating Components

Generate production-ready components with AI assistance:

Modern button variants with accessibility features
Responsive card layouts with proper spacing
Form components with validation styling
Navigation menus with mobile-first design

Design Optimization

Improve existing designs with intelligent analysis:

Remove redundant Tailwind classes
Resolve conflicting utility classes
Optimize for performance and maintainability
Enhance accessibility compliance

Theme Development

Build comprehensive design systems:

Generate cohesive color palettes
Create typography scales
Design spacing systems
Export Tailwind configuration files

🌐 Cross-Platform Usage

Multi-Framework Development

// Convert HTML component to any framework
{
  "tool": "generate_component",
  "description": "Modern button component",
  "framework": "react", // or "vue", "svelte", "angular"
  "typescript": true,
  "features": ["loading-state", "variant-support"]
}

Universal Project Generation

// Create full-stack project with any tech stack
{
  "tool": "create_project",
  "name": "My App",
  "framework": "react",
  "buildTool": "vite", // or "webpack", "nextjs", "nuxt"
  "features": ["typescript", "tailwind", "testing", "deployment"]
}

Platform Integration

# VS Code Extension
code --install-extension tailwind-mcp-assistant

# WebStorm Plugin  
# Install from JetBrains Marketplace: "Tailwind MCP Assistant"

# Figma Plugin
# Search "Tailwind MCP" in Figma Community

# CLI Tool
npm install -g tailwind-mcp-cli
tmcp generate --framework react --description "Product card"

# Browser Extension
# Install from Chrome Web Store: "Tailwind MCP Assistant"

Cross-Platform Workflow

# 1. Design in Figma → Extract with plugin
# 2. Convert to multiple frameworks  
tmcp convert --from figma --to react,vue,svelte

# 3. Generate optimized projects
tmcp create-project --framework react --build vite
tmcp create-project --framework vue --build nuxt

# 4. Deploy to multiple platforms
tmcp deploy --platforms vercel,netlify,aws

Code Migration

Convert existing CSS to Tailwind:

Transform legacy CSS to utility classes
Migrate from other frameworks
Optimize class usage patterns
Maintain visual consistency

🔧 Development

Running Locally

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

Testing MCP Server

Test with echo command:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

Test with a simple tool call:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "generate_component", "arguments": {"description": "A simple button", "type": "button"}}}' | node dist/index.js

Test with environment variable:

GEMINI_API_KEY="your_key" node dist/index.js

Environment Variables

GEMINI_API_KEY: Your Google Gemini API key (optional)
NODE_ENV: Environment mode (development/production)

Project Structure

src/
├── index.ts              # Main MCP server
├── tools/                # MCP tool implementations
│   ├── component-generator.ts
│   ├── class-optimizer.ts
│   ├── theme-creator.ts
│   ├── design-analyzer.ts
│   ├── preview-generator.ts
│   ├── css-converter.ts
│   ├── ai-suggestions.ts
│   └── layout-generator.ts
└── utils/
    └── gemini.ts          # Gemini AI integration

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

Development Setup

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🐳 Docker Deployment

Quick Docker Setup

# Build production image
docker build -f Dockerfile.runtime -t mcp-tailwind-runtime:latest .

# Run container
docker run -d \
  --name mcp-tailwind-server \
  --env-file .env \
  --restart unless-stopped \
  mcp-tailwind-runtime:latest

Docker Compose (Recommended)

# Start production stack
docker-compose -f docker-compose.prod.yml up -d

# View logs
docker-compose -f docker-compose.prod.yml logs -f

# Stop services
docker-compose -f docker-compose.prod.yml down

Security Best Practices

Environment Variables:

# Use .env file (never commit to Git)
cp env.example .env
# Edit .env with your actual API key

Container Security:

# Run with resource limits
docker run -d \
  --name mcp-tailwind-server \
  --env-file .env \
  --memory=512m \
  --cpus=1.0 \
  --restart unless-stopped \
  mcp-tailwind-runtime:latest

Network Isolation:

# Create isolated network
docker network create mcp-network

# Run with custom network
docker run -d \
  --name mcp-tailwind-server \
  --network mcp-network \
  --env-file .env \
  --restart unless-stopped \
  mcp-tailwind-runtime:latest

For detailed Docker and security guide, see DOCKER-SECURITY-GUIDE.md.

🔧 Troubleshooting

Common Issues

MCP Server not starting:
- Ensure you've run npm run build first
- Check that dist/index.js exists
- Verify Node.js version is 18+
Gemini API errors:
- Set your GEMINI_API_KEY environment variable
- Verify the API key is valid and has proper permissions
- Check your internet connection

Docker container issues:

# Check container logs
docker logs mcp-tailwind-server

# Verify environment
docker exec mcp-tailwind-server env | grep GEMINI

# Restart container
docker restart mcp-tailwind-server

Claude Desktop not connecting:
- Restart Claude Desktop after updating config
- Check the config file path is correct
- Verify JSON syntax is valid

Build errors:

# Clean and rebuild
rm -rf dist/ node_modules/
npm install
npm run build

Debug Mode

# Run with debug logging
DEBUG=mcp:* node dist/index.js

# Docker debug
docker run -it --rm \
  --env-file .env \
  mcp-tailwind-runtime:latest npm run dev

🙋‍♂️ Support

Issues: GitHub Issues
Documentation: Check the examples in this README
Discussions: GitHub Discussions

Built with ❤️ for the Tailwind CSS and AI community