Skip to main content
Glama

MCP Color Server

A comprehensive DeveloperTools Server and MCP that provides advanced color manipulation, palette generation, gradient creation, and visualization capabilities to AI applications.

Features

  • Comprehensive Color Format Support: Convert between 22+ formats including HEX, RGB, HSL, HSV, HWB, CMYK, LAB, XYZ, LCH, OKLAB, OKLCH, and named colors

  • Framework Integration: Native support for CSS variables, SCSS, Tailwind classes, Swift UIColor, Android Color, and Flutter Color formats

  • High-Precision Conversion: Configurable precision up to 10 decimal places for scientific and professional applications

  • Palette Generation: Create harmonious color palettes based on color theory principles

  • Gradient Creation: Generate linear, radial, and conic gradients with advanced interpolation

  • Accessibility Compliance: WCAG 2.1 AA/AAA contrast checking and colorblind simulation

  • Dual Background Visualization: Create interactive HTML and high-quality PNG visualizations with both light and dark background variants

  • Export Formats: Generate CSS, SCSS, Tailwind CSS, and JSON exports for seamless integration

  • Theme Generation: Generate complete design system themes with semantic color mapping

  • Performance Optimized: Sub-100ms response times for all color operations with intelligent caching

Related MCP server: MCP Color Converter

Installation

Prerequisites

  • Node.js 20.0.0 or higher

  • npm or yarn package manager

Install Dependencies

npm install

Development Setup

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

Usage

As an MCP Server

The color server implements the Model Context Protocol and can be used with any MCP-compatible client.

Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "color": {
      "command": "node",
      "args": ["path/to/mcp-color-server/dist/index.js"]
    }
  }
}

Available Tools

  • convert_color: Convert colors between different formats

  • analyze_color: Analyze color properties (brightness, contrast, temperature)

  • generate_harmony_palette: Create color palettes based on harmony principles

  • generate_gradient: Create CSS gradients with advanced options

  • check_contrast: Verify WCAG accessibility compliance

  • create_palette_html: Generate interactive HTML visualizations

  • create_palette_png: Generate high-quality PNG images

  • export_css: Generate modern CSS with custom properties and utility classes

  • export_scss: Generate SCSS variables, maps, and mixins

  • export_tailwind: Generate Tailwind CSS configuration and utility classes

  • export_json: Generate JSON format for programmatic use and API integration

API

MCP Protocol

The server implements the Model Context Protocol (MCP) specification and provides the following endpoints:

Tool Discovery

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Tool Execution

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "convert_color",
    "arguments": {
      "color": "#FF0000",
      "output_format": "hsl"
    }
  }
}

Response Format

All tools return responses in this standardized format:

{
  "success": true,
  "data": {
    "converted": "hsl(0, 100%, 50%)",
    "original": "#FF0000"
  },
  "metadata": {
    "execution_time": 15,
    "color_space_used": "sRGB",
    "accessibility_notes": [],
    "recommendations": []
  },
  "visualizations": {
    "html": "<!DOCTYPE html>...",
    "png_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "export_formats": {
    "css": ":root { --color: #FF0000; }",
    "scss": "$color: #FF0000;",
    "tailwind": "{ colors: { custom: '#FF0000' } }",
    "json": { "hex": "#FF0000", "rgb": "rgb(255, 0, 0)" }
  }
}

Supported Color Formats

Input Formats

The MCP Color Server accepts colors in any of these formats:

Standard Web Formats

  • HEX: #FF0000, #F00, FF0000, F00

  • RGB: rgb(255, 0, 0), 255, 0, 0, 255 0 0, [255, 0, 0]

  • RGBA: rgba(255, 0, 0, 0.5)

  • HSL: hsl(0, 100%, 50%), 0, 100%, 50%

  • HSLA: hsla(0, 100%, 50%, 0.8)

  • HSV/HSB: hsv(0, 100%, 100%), hsb(0, 100%, 100%)

  • HSVA: hsva(0, 100%, 100%, 0.7)

Advanced Color Spaces

  • HWB: hwb(0, 0%, 0%)

  • CMYK: cmyk(0%, 100%, 100%, 0%)

  • LAB: lab(53.23, 80.11, 67.22)

  • XYZ: xyz(41.24, 21.26, 1.93)

  • LCH: lch(53.23, 104.55, 40.85)

  • OKLAB: oklab(0.628, 0.225, 0.126)

  • OKLCH: oklch(0.628, 0.258, 29.23)

Named Colors

  • CSS Named Colors: red, blue, forestgreen, lightsteelblue, etc.

Output Formats

Convert to any of these formats with configurable precision:

Web Development

{
  "color": "#FF0000",
  "output_format": "hex"
}
// Result: "#ff0000"

{
  "color": "#FF0000",
  "output_format": "rgb"
}
// Result: "rgb(255, 0, 0)"

{
  "color": "#FF0000",
  "output_format": "hsl",
  "precision": 1
}
// Result: "hsl(0.0, 100.0%, 50.0%)"

CSS Variables

{
  "color": "#FF0000",
  "output_format": "css-var",
  "variable_name": "primary-color"
}
// Result: "--primary-color: #ff0000;"

{
  "color": "#FF0000",
  "output_format": "scss-var",
  "variable_name": "accent_color"
}
// Result: "$accent_color: #ff0000;"

Mobile Development

{
  "color": "#FF0000",
  "output_format": "swift",
  "precision": 3
}
// Result: "UIColor(red: 1.000, green: 0.000, blue: 0.000, alpha: 1.000)"

{
  "color": "#FF0000",
  "output_format": "android"
}
// Result: "Color.parseColor(\"#FFFF0000\")"

{
  "color": "#FF0000",
  "output_format": "flutter"
}
// Result: "Color(0xFFFF0000)"

Framework Integration

{
  "color": "#FF0000",
  "output_format": "tailwind"
}
// Result: "red-500"

Scientific/Professional

{
  "color": "#FF0000",
  "output_format": "lab",
  "precision": 6
}
// Result: "lab(53.230000, 80.110000, 67.220000)"

{
  "color": "#FF0000",
  "output_format": "oklab",
  "precision": 8
}
// Result: "oklab(0.62800000, 0.22500000, 0.12600000)"

Usage Examples

Basic Color Conversion

// Convert HEX to RGB
{
  "tool": "convert_color",
  "parameters": {
    "color": "#FF0000",
    "output_format": "rgb"
  }
}

// Convert RGB to HSL with high precision
{
  "tool": "convert_color",
  "parameters": {
    "color": "rgb(255, 128, 64)",
    "output_format": "hsl",
    "precision": 4
  }
}

Advanced Color Space Conversions

// Convert to LAB color space for perceptual uniformity
{
  "tool": "convert_color",
  "parameters": {
    "color": "#FF8040",
    "output_format": "lab",
    "precision": 3
  }
}

// Convert to OKLCH for modern color workflows
{
  "tool": "convert_color",
  "parameters": {
    "color": "hsl(25, 100%, 69%)",
    "output_format": "oklch",
    "precision": 5
  }
}

Framework-Specific Outputs

// Generate Swift UIColor
{
  "tool": "convert_color",
  "parameters": {
    "color": "#2563eb",
    "output_format": "swift",
    "precision": 3
  }
}

// Generate Tailwind CSS class
{
  "tool": "convert_color",
  "parameters": {
    "color": "#ef4444",
    "output_format": "tailwind"
  }
}

// Generate CSS custom property
{
  "tool": "convert_color",
  "parameters": {
    "color": "#10b981",
    "output_format": "css-var",
    "variable_name": "success-color"
  }
}

Export Format Generation

Generate complete stylesheets and configuration files:

// Generate CSS with custom properties
{
  "tool": "export_css",
  "parameters": {
    "colors": ["#2563eb", "#ef4444", "#10b981"],
    "format": "both",
    "semantic_names": ["primary", "error", "success"],
    "include_rgb_hsl": true
  }
}

// Generate SCSS with mixins
{
  "tool": "export_scss",
  "parameters": {
    "colors": ["#2563eb", "#ef4444"],
    "format": "all",
    "include_functions": true,
    "namespace": "theme"
  }
}

// Generate Tailwind config
{
  "tool": "export_tailwind",
  "parameters": {
    "colors": ["#2563eb"],
    "include_shades": true,
    "semantic_names": ["primary"]
  }
}

// Generate JSON with metadata
{
  "tool": "export_json",
  "parameters": {
    "colors": ["#2563eb", "#ef4444"],
    "format": "detailed",
    "include_accessibility": true,
    "group_name": "Brand Colors"
  }
}

Performance Characteristics

  • Single Conversions: < 100ms response time

  • Batch Operations: < 20ms average per conversion

  • High Precision: Up to 10 decimal places without performance impact

  • Memory Efficient: Optimized for concurrent operations

  • Caching: Intelligent caching for frequently converted colors

Direct Usage

import { ColorServer } from './src/server.js';

const server = new ColorServer();
// Server usage examples will be added as implementation progresses

Development

Project Structure

mcp-color-server/
├── src/                    # Source code
│   ├── server.ts          # Main MCP server implementation
│   ├── tools/             # Tool implementations
│   ├── validation/        # Input validation schemas
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Utility functions
├── tests/                 # Test files
├── docs/                  # Documentation
├── examples/              # Usage examples
└── dist/                  # Compiled output

Code Quality

This project maintains high code quality standards with automated Git hooks:

  • Pre-commit Hooks: Automatic linting, formatting, and type checking on staged files

  • Pre-push Hooks: Full test suite with 90%+ coverage requirements and build verification

  • Commit Message Validation: Enforces conventional commit format

  • Zero-Defect Policy: No TypeScript errors, ESLint warnings, or failing tests allowed

See Husky Setup Documentation for detailed information about our Git hooks.

  • TypeScript: Strict mode enabled with comprehensive type checking

  • ESLint: Enforces code style and catches potential issues

  • Prettier: Automatic code formatting

  • Jest: Comprehensive test suite with 90%+ coverage requirement

  • Continuous Integration: Automated testing and quality checks

Contributing

Please read docs/contributing.md for details on our code of conduct and the process for submitting pull requests.

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run specific test file
npm test -- server.test.ts

Building

# Clean previous build
npm run clean

# Build for production
npm run build

# Type check without building
npm run type-check

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions! Please see docs/contributing.md for guidelines.

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code.

Support

Production Deployment

System Requirements

  • Node.js: 20.0.0 or higher

  • Memory: 512MB minimum, 2GB recommended

  • CPU: 1 core minimum, 2+ cores recommended for high load

  • Storage: 100MB for application, additional space for logs and cache

Performance Characteristics

  • Response Times: < 100ms for color conversions, < 2s for complex visualizations

  • Throughput: 50+ concurrent requests supported

  • Memory Usage: < 100MB per request, intelligent caching and cleanup

  • Reliability: 99.9% uptime with proper deployment and monitoring

Deployment Options

Docker Deployment

# Build Docker image
docker build -t mcp-color-server .

# Run container
docker run -d \
  --name mcp-color-server \
  -e NODE_ENV=production \
  -e LOG_LEVEL=info \
  -p 3000:3000 \
  mcp-color-server

PM2 Deployment

# Install PM2 globally
npm install -g pm2

# Start with PM2
pm2 start ecosystem.config.js

# Save PM2 configuration
pm2 save
pm2 startup

Systemd Service

# Copy service file
sudo cp mcp-color-server.service /etc/systemd/system/

# Enable and start service
sudo systemctl enable mcp-color-server
sudo systemctl start mcp-color-server

Monitoring and Maintenance

  • Health Checks: Built-in health endpoint at /health

  • Metrics: Performance metrics and resource usage tracking

  • Logging: Structured JSON logging with configurable levels

  • Alerts: Memory usage, response time, and error rate monitoring

Security

Security Features

  • Input Validation: Comprehensive validation for all color formats and parameters

  • XSS Prevention: Sanitization of generated HTML, CSS, and SVG content

  • Rate Limiting: Built-in rate limiting for expensive operations

  • Resource Protection: Memory limits, processing timeouts, and cleanup

  • Audit Logging: Security-relevant events logged without exposing sensitive data

Security Best Practices

  1. Run with minimal privileges: Use dedicated user account

  2. Network security: Run behind reverse proxy with HTTPS

  3. Resource limits: Configure appropriate memory and CPU limits

  4. Regular updates: Keep dependencies updated for security patches

  5. Monitoring: Monitor for suspicious activity and resource usage

Vulnerability Reporting

Report security vulnerabilities privately to: security@mcp-color-server.org

See docs/security.md for detailed security policy and reporting procedures.

Roadmap

Current Version (0.1.0)

  • ✅ Complete color format conversion system

  • ✅ Palette generation with color theory algorithms

  • ✅ Gradient creation and visualization

  • ✅ Theme generation and semantic color mapping

  • ✅ Accessibility compliance tools

  • ✅ HTML and PNG visualization generation

  • ✅ Export formats (CSS, SCSS, Tailwind, JSON)

  • ✅ Performance optimization and caching

  • ✅ Security hardening and input validation

Planned Features (Future Releases)

  • 🔄 3D color space visualizations

  • 🔄 Color animation and transitions

  • 🔄 Advanced image color extraction

  • 🔄 Educational content and tutorials

  • 🔄 Plugin architecture for custom algorithms

  • 🔄 RESTful API endpoints

  • 🔄 Advanced gradient types (mesh, conic)

  • 🔄 Mobile framework integrations

Community Contributions Welcome

  • Color theory algorithm improvements

  • New export format support

  • Performance optimizations

  • Documentation enhancements

  • Test coverage improvements

  • Accessibility features

Available Tools

25 tools
analyze_colorC

Analyze color properties including brightness, temperature, contrast, accessibility, and optionally compare with another color

analyze_color_collectionC

Analyze a collection of colors for diversity, harmony, contrast range, temperature distribution, and accessibility metrics.

Inputs: colors (required), metrics.

check_contrastC

Check color contrast compliance with WCAG accessibility standards

Inputs: foreground (required), background (required), text_size, standard.

convert_colorB

Convert colors between different formats with high precision and comprehensive format support

Inputs: color (required), output_format (required), precision, variable_name.

create_color_comparison_pngC

Generate PNG images comparing multiple color sets with various visualization styles

Inputs: color_sets (required), comparison_type, chart_style, annotations, +3 more.

create_color_wheel_htmlB

Generate interactive HTML color wheel visualizations with harmony highlighting and color selection

create_gradient_htmlB

Generate HTML gradient preview visualizations with CSS code display and interactive controls

create_gradient_pngB

Generate high-quality PNG images of gradients with various styles and effects

Inputs: gradient (required), dimensions (required), resolution, format, +2 more.

create_palette_htmlB

Generate interactive HTML visualizations of color palettes with accessibility features and multiple layout options

create_palette_pngC

Generate high-quality PNG images of color palettes with professional layout and styling options

Inputs: palette (required), layout, resolution, dimensions, +6 more.

create_theme_preview_htmlC

Generate HTML theme preview mockups showing colors in realistic UI contexts

export_cssC

Generate modern CSS with custom properties, utility classes, and fallbacks for color palettes

export_jsonC

Generate JSON format for programmatic use and API integration with multiple structure options

export_scssB

Generate SCSS variables, maps, and mixins for color palettes with utility functions

export_tailwindC

Generate Tailwind CSS configuration, plugins, and utility classes for color palettes

generate_color_variationsB

Generate tints, shades, and tones of a base color with mathematical precision. Tints add white, shades add black, and tones add gray.

Inputs: base_color (required), variation_type (required), steps, intensity.

generate_harmony_paletteC

Generate color palettes based on color theory harmony principles including complementary, triadic, analogous, and other harmony types

Inputs: base_color (required), harmony_type (required), count, variation.

generate_linear_gradientC

Generate linear gradients with precise mathematical control and CSS output

Inputs: colors (required), positions, angle, interpolation, +2 more.

generate_radial_gradientC

Generate radial gradients with precise mathematical control and CSS output

Inputs: colors (required), positions, center, shape, +5 more.

generate_semantic_colorsB

Map colors to semantic roles for UI design with accessibility compliance

Inputs: base_palette (required), semantic_roles, context, ensure_contrast, +1 more.

generate_themeC

Generate complete design system themes with semantic color mapping

Inputs: theme_type (required), primary_color (required), style, components, +2 more.

mix_colorsC

Mix multiple colors with specified ratios and blend modes. Supports various color spaces and blend modes for different mixing effects.

Inputs: colors (required), ratios, blend_mode, color_space.

optimize_for_accessibilityC

Optimize colors for accessibility compliance while preserving hue when possible

Inputs: palette (required), use_cases (required), target_standard, preserve_hue, +1 more.

simulate_colorblindnessC

Simulate how colors appear to users with color vision deficiencies

Inputs: colors (required), type (required), severity.

sort_colorsB

Sort colors by various properties including hue, saturation, lightness, brightness, temperature, or frequency. Optionally group similar colors together.

Inputs: colors (required), sort_by (required), direction, group_similar.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 25 tools

    Disambiguation3/5

    The tools have clear individual purposes, but significant overlap exists in visualization and export functions. For example, create_palette_html and create_palette_png serve similar purposes with different output formats, as do the multiple gradient and export tools. Descriptions help differentiate, but agents might struggle choosing between format-specific variants.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, with clear action prefixes like analyze_, check_, convert_, create_, export_, generate_, mix_, optimize_, simulate_, and sort_. All names use snake_case consistently, making them predictable and readable.

    Tool Count2/5

    With 25 tools, this server feels overloaded for a color manipulation domain. Many tools could be consolidated (e.g., multiple create_* and export_* variants), leading to redundancy. A more focused set of 10-15 tools would better serve the core functionality without overwhelming agents.

    Completeness5/5

    The toolset provides comprehensive coverage for color manipulation, analysis, visualization, and integration. It includes core operations (convert, mix, generate variations), accessibility features, multiple output formats, and design system support. No obvious gaps exist; agents can perform complete color workflow tasks.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides comprehensive color conversion, manipulation, analysis, and WCAG accessibility tools supporting multiple formats (hex, rgb, hsl, oklch, oklab) for design systems and web development.
      24 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive toolkit for color conversion, manipulation, and accessibility analysis supporting formats like OkLCH and WCAG compliance. It enables AI agents to manage design systems by generating harmonious palettes, transforming color spaces, and performing contrast checks.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Extract palettes from images, generate harmonies, gradients, random palettes; Check WCAG and APCA contrast; Suggest nearest passing OkLCH lightness; Simulate color-blindness; Convert and sort colors across formats (hex / RGB / HSL / OkLCH / …)
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides color and design tools including palette generation, WCAG contrast checking, color conversion, gradients, color blindness simulation, and CSS variables, all without API keys.
      MIT