npm package: @iflow-mcp/coppinaphil-tailwind-mcp-server
Description: The first and most comprehensive MCP server for Tailwind CSS - generate components, optimize classes, create themes, and get best practices guidance
Author: Philip Fedele
Latest version: 1.0.1

# 🎨 Tailwind MCP Server

<div align="center">

[![npm version](https://badge.fury.io/js/tailwind-mcp-server.svg)](https://badge.fury.io/js/tailwind-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/tailwind-mcp-server.svg)](https://nodejs.org/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)

**The first and most comprehensive Model Context Protocol (MCP) server for Tailwind CSS**

*Generate components • Optimize classes • Create themes • Get best practices*

[Installation](#-installation) • [Features](#-features) • [Usage](#-usage) • [Examples](#-examples) • [Contributing](#-contributing)

</div>

---

## 🚀 Features

### 🎯 **Component Generation**
Generate production-ready Tailwind components with variants, sizes, and framework support
- **UI Elements**: buttons, cards, modals, alerts, badges, dropdowns, tooltips
- **Navigation**: navbars, sidebars, breadcrumbs, pagination, tabs  
- **Layout**: hero sections, footers, grid layouts, flexbox patterns
- **Forms**: complete form components with validation styling
- **Data Display**: tables, accordions, progress bars

### ⚡ **Smart Optimization**
- **Class Optimization**: Clean up redundant classes and merge conflicts
- **Validation**: Validate Tailwind classes with improvement suggestions
- **Performance Tips**: Get guidance on bundle size and optimization

### 📱 **Layout Systems**
- **Responsive Layouts**: Mobile-first flexbox, grid, and dashboard layouts
- **Design Patterns**: Blog, e-commerce, landing page, and dashboard templates
- **Breakpoint Strategies**: Comprehensive responsive design guidance

### 🎨 **Theme Creation**
- **Color Palettes**: Generate cohesive color systems from brand colors
- **Typography**: Create consistent font scales and hierarchy
- **Design Systems**: Complete theme generation with spacing, shadows, borders
- **Configuration**: Export themes as `tailwind.config.js` files

### 🔧 **Developer Tools**
- **CSS Conversion**: Transform existing CSS to Tailwind classes
- **Configuration Generation**: Create framework-specific Tailwind configs
- **Best Practices**: Get guidance on accessibility, performance, maintainability
- **Plugin Recommendations**: Suggestions based on your project needs

### 🌐 **Framework Support**
- **HTML** - Pure HTML with Tailwind classes
- **React** - JSX components with TypeScript support
- **Vue** - Vue.js single file components
- **Svelte** - Svelte component format
- **Angular** - Angular template format

---

## 📦 Installation

### NPM Installation
```bash
npm install -g tailwind-mcp-server
```

### Manual Installation
```bash
git clone https://github.com/yourusername/tailwind-mcp-server.git
cd tailwind-mcp-server
npm install
```

---

## ⚙️ Configuration

### Claude Desktop Setup
Add to your `claude_desktop_config.json`:

**Option 1: Global Installation (Recommended)**
```json
{
  "mcpServers": {
    "tailwind-mcp-server": {
      "command": "npx",
      "args": ["tailwind-mcp-server"]
    }
  }
}
```

**Option 2: Manual Installation**
```json
{
  "mcpServers": {
    "tailwind-mcp-server": {
      "command": "node",
      "args": ["/path/to/tailwind-mcp-server/src/server.js"]
    }
  }
}
```

**Config File Locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

---

## 🛠️ Available Tools

| Tool | Description | Use Case |
|------|-------------|----------|
| `generate_component` | Generate Tailwind components | Create buttons, cards, navigation |
| `optimize_classes` | Clean up class lists | Remove redundancy, merge conflicts |
| `validate_classes` | Validate Tailwind classes | Check syntax, get suggestions |
| `generate_layout` | Create responsive layouts | Build page structures |
| `create_theme` | Generate design systems | Create color palettes, typography |
| `generate_config` | Create Tailwind configs | Framework-specific setups |
| `convert_css_to_tailwind` | Convert CSS to Tailwind | Migrate existing styles |
| `get_responsive_patterns` | Get responsive patterns | Mobile-first design guidance |
| `get_best_practices` | Best practices guidance | Performance, accessibility tips |
| `suggest_plugins` | Plugin recommendations | Find the right plugins |

---

## 📚 Usage Examples

### 🔲 Generate a Modern Button
```json
{
  "component_type": "button",
  "variant": "primary",
  "size": "lg",
  "responsive": true,
  "dark_mode": true,
  "framework": "react"
}
```

**Output:**
```jsx
const Button = ({ children, onClick, disabled = false }) => {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      className="inline-flex items-center justify-center px-6 py-3 text-lg font-medium text-white bg-blue-600 border border-transparent rounded-lg shadow-sm hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors duration-200 dark:bg-blue-500 dark:hover:bg-blue-600 sm:px-8 sm:py-4"
    >
      {children}
    </button>
  );
};
```

### 🎨 Create a Color Theme
```json
{
  "theme_type": "colors",
  "style": "modern",
  "brand_color": "#6366F1",
  "color_count": 9,
  "include_config": true
}
```

### 📱 Generate Responsive Layout
```json
{
  "layout_type": "dashboard",
  "complexity": "medium",
  "responsive": true,
  "content_areas": ["header", "sidebar", "main", "footer"]
}
```

### ⚡ Optimize Classes
```json
{
  "classes": "p-4 px-4 py-4 text-blue-500 text-blue-600 flex flex-row",
  "merge_conflicts": true,
  "remove_redundant": true,
  "suggest_alternatives": true
}
```

**Output:**
```json
{
  "optimized_classes": "p-4 text-blue-600 flex",
  "removed_redundant": ["px-4", "py-4", "text-blue-500", "flex-row"],
  "suggestions": ["Consider using 'space-x-*' for gap between flex items"]
}
```

---

## 🎯 Component Showcase

### Buttons
- **Variants**: primary, secondary, outline, ghost, link
- **Sizes**: xs, sm, md, lg, xl
- **States**: hover, focus, active, disabled
- **Features**: loading states, icon support, responsive sizing

### Cards
- **Types**: basic, elevated, outlined, interactive
- **Features**: headers, footers, media support, hover effects
- **Layouts**: vertical, horizontal, grid arrangements

### Navigation
- **Components**: navbar, sidebar, breadcrumbs, pagination
- **Features**: mobile-responsive, dropdown menus, active states
- **Accessibility**: keyboard navigation, ARIA labels

### Forms
- **Elements**: inputs, selects, textareas, checkboxes, radios
- **Features**: validation states, help text, floating labels
- **Layouts**: inline, stacked, grid arrangements

---

## 🏗️ Layout Examples

### Dashboard Layout
```html
<div class="min-h-screen bg-gray-50 dark:bg-gray-900">
  <!-- Header -->
  <header class="bg-white dark:bg-gray-800 shadow-sm border-b border-gray-200 dark:border-gray-700">
    <!-- Header content -->
  </header>
  
  <div class="flex">
    <!-- Sidebar -->
    <aside class="w-64 bg-white dark:bg-gray-800 shadow-sm">
      <!-- Sidebar content -->
    </aside>
    
    <!-- Main content -->
    <main class="flex-1 p-6">
      <!-- Page content -->
    </main>
  </div>
</div>
```

### Hero Section
```html
<section class="relative bg-gradient-to-r from-purple-600 to-blue-600 dark:from-purple-800 dark:to-blue-800">
  <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-24 sm:py-32">
    <div class="text-center">
      <h1 class="text-4xl font-bold tracking-tight text-white sm:text-6xl">
        Beautiful Tailwind Components
      </h1>
      <p class="mt-6 text-lg leading-8 text-purple-100">
        Generate, optimize, and perfect your Tailwind CSS with AI assistance
      </p>
    </div>
  </div>
</section>
```

---

## 🎨 Theme Examples

### Modern Color Palette
```javascript
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          200: '#bfdbfe',
          300: '#93c5fd',
          400: '#60a5fa',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
          800: '#1e40af',
          900: '#1e3a8a',
        }
      }
    }
  }
}
```

### Typography Scale
```javascript
fontSize: {
  'xs': ['0.75rem', { lineHeight: '1rem' }],
  'sm': ['0.875rem', { lineHeight: '1.25rem' }],
  'base': ['1rem', { lineHeight: '1.5rem' }],
  'lg': ['1.125rem', { lineHeight: '1.75rem' }],
  'xl': ['1.25rem', { lineHeight: '1.75rem' }],
  '2xl': ['1.5rem', { lineHeight: '2rem' }],
  '3xl': ['1.875rem', { lineHeight: '2.25rem' }],
  '4xl': ['2.25rem', { lineHeight: '2.5rem' }],
}
```

---

## 📋 Best Practices

### Performance
- **Purge unused classes** with proper content configuration
- **Use @apply directive** sparingly for maintainability
- **Optimize for production** with minification and compression
- **Leverage JIT mode** for faster builds and smaller bundles

### Responsive Design
- **Mobile-first approach** with progressive enhancement
- **Consistent breakpoints** across the design system
- **Touch-friendly targets** (minimum 44px touch targets)
- **Flexible grid systems** for various content types

### Accessibility
- **Semantic HTML** structure with proper headings
- **Color contrast** meeting WCAG guidelines
- **Keyboard navigation** support for all interactive elements
- **Screen reader** compatibility with proper ARIA labels

### Maintainability
- **Component-based** architecture for reusability
- **Design tokens** for consistent theming
- **Documentation** for custom utilities and components
- **Version control** for configuration changes

---

## 🔌 Plugin Recommendations

### Essential Plugins
- **@tailwindcss/forms** - Better form styling
- **@tailwindcss/typography** - Rich content styling
- **@tailwindcss/aspect-ratio** - Responsive media

### Specialized Plugins
- **@tailwindcss/line-clamp** - Text truncation
- **tailwindcss-animate** - Animation utilities
- **@tailwindcss/container-queries** - Container-based responsive design

---

## 🤝 Contributing

We welcome contributions! Here's how to get started:

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make your changes** and add tests if applicable
4. **Commit your changes**: `git commit -m 'Add amazing feature'`
5. **Push to the branch**: `git push origin feature/amazing-feature`
6. **Open a Pull Request**

### Development Setup
```bash
git clone https://github.com/yourusername/tailwind-mcp-server.git
cd tailwind-mcp-server
npm install
npm run dev
```

### Areas for Contribution
- Additional component types
- More layout patterns
- Enhanced optimization algorithms
- Better CSS-to-Tailwind conversion
- Extended theme generation
- More framework support

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙋‍♂️ Support

- **Documentation**: Check our [examples](examples/) directory
- **Issues**: [GitHub Issues](https://github.com/yourusername/tailwind-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/tailwind-mcp-server/discussions)

---

## 🌟 Show Your Support

If this project helps you, please consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs or requesting features
- 🤝 Contributing to the codebase
- 📢 Sharing with other developers

---

<div align="center">

**Built with ❤️ for the Tailwind CSS community**


</div>