color-tools

ohqay/color-tools

3.2

If you are the rightful owner of color-tools and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server that enables Claude to work with colors, offering conversion, harmony generation, and palette access.

Tools
4
Resources
0
Prompts
0

Color Tools

 ██████╗  ██████╗ ██╗      ██████╗ ██████╗
 ██╔════╝██╔═══██╗██║     ██╔═══██╗██╔══██╗
 ██║     ██║   ██║██║     ██║   ██║██████╔╝
 ██║     ██║   ██║██║     ██║   ██║██╔══██╗
 ╚██████╗╚██████╔╝███████╗╚██████╔╝██║  ██║
  ╚═════╝ ╚═════╝ ╚══════╝ ╚═════╝ ╚═╝  ╚═╝
 ████████╗ ██████╗  ██████╗ ██╗     ███████╗
 ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝
    ██║   ██║   ██║██║   ██║██║     ███████╗
    ██║   ██║   ██║██║   ██║██║     ╚════██║
    ██║   ╚██████╔╝╚██████╔╝███████╗███████║
    ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝

A comprehensive Model Context Protocol (MCP) server that provides advanced color manipulation, accessibility analysis, and scientific color space tools for AI assistants. Features intelligent color conversion, harmony generation, WCAG compliance checking, color blindness simulation, and extensive Tailwind CSS integration.

Features

Color Format Support

  • Universal color format conversion between 10+ formats:
    • Hexadecimal (e.g., #D4C7BA, #FFF, #RGBA, #RRGGBBAA)
    • RGB/RGBA (e.g., rgb(212, 199, 186), rgba(255, 0, 0, 0.5))
    • HSL/HSLA (e.g., hsl(30, 24%, 78%), hsla(30, 24%, 78%, 0.8))
    • HSB/HSV (e.g., hsb(30, 12%, 83%), hsv(240, 100%, 100%))
    • CMYK (e.g., cmyk(0%, 6%, 12%, 17%))
    • LAB (CIE LAB color space for scientific applications)
    • XYZ (CIE XYZ tristimulus values for advanced color science)
  • Intelligent auto-detection of input color format
  • CSS named colors support (147 colors like red, blue, coral)
  • Extended hex format support with alpha channel (#RGBA, #RRGGBBAA)
  • Batch conversion to multiple output formats in a single operation

Color Theory & Harmonies

  • Advanced color harmony generation based on color theory:
    • Complementary (opposite colors)
    • Analogous (adjacent colors)
    • Triadic (three evenly spaced)
    • Tetradic/Square (four evenly spaced)
    • Split-complementary (base + two adjacent to complement)
    • Double-complementary (two complementary pairs)
  • Custom angle adjustments for fine-tuning harmonies
  • Perceptually uniform color mixing in LAB color space
  • Multiple blend modes: normal, multiply, screen, overlay

Accessibility & Inclusivity

  • WCAG contrast ratio calculation with AA/AAA compliance checking
  • Color blindness simulation for 8 different types:
    • Protanopia, Protanomaly, Deuteranopia, Deuteranomaly
    • Tritanopia, Tritanomaly, Achromatopsia, Achromatomaly
  • Accessible color finder that maintains hue while meeting WCAG standards
  • Accessibility recommendations with actionable suggestions

Developer Experience

  • Tailwind CSS integration with full V3 and V4 support:
    • Color name to hex conversion
    • Hex to Tailwind name lookup
    • Fuzzy search and similar color finding
    • All 6 operation types supported
  • Performance optimized with intelligent caching and lazy loading
  • Comprehensive error handling with structured, actionable error messages
  • Intelligent defaults - returns common formats when none specified
  • Rich MCP Resources for accessing curated color palettes

Color Palettes & Resources

  • Material Design color palette (19 colors, 190+ shades)
  • Tailwind CSS V3 palette (22 colors, 220+ shades)
  • Tailwind CSS V4 modernized OKLCH-based palette with P3 color gamut support
  • CSS named colors organized by category (147 colors)
  • Web-safe colors (216 colors for cross-browser compatibility)

Installation

  1. Clone this repository:
git clone https://github.com/ohqay/color-tools.git
cd color-tools
  1. Install dependencies:
npm install
  1. Build the project:
npm run build
  1. Run tests:
bun test

Note: This project uses Bun as the test runner for optimal performance. Tests can be run with bun test, bun test --coverage, or bun test --watch for development.

Usage

Configuring Claude Desktop

Add the following to your Claude Desktop configuration file:

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

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

Replace /path/to/color-tools with the actual path to your installation.

Using the Tools

Once configured, you can use the tools in Claude:

convert-color
Convert #D4C7BA to RGB format

Convert rgb(212, 199, 186) to specific formats: ["hex", "hsl", "cmyk"]

Convert "coral" to hex, rgb, and hsl

Convert rgba(255, 0, 0, 0.5) to hsla
color-info
Get information about the color converter
generate-harmony
Generate a complementary color scheme for #FF6B6B

Create a triadic harmony from blue in RGB format

Generate analogous colors from #4ECDC4 with 5 colors
convert-tailwind-color
Convert blue-500 to hex format (to-hex operation)

Find the exact Tailwind color name for hex #3b82f6 (from-hex operation)

Get all shades of the blue color in RGB format (get-all-shades operation)

Search for red colors in the Tailwind palette (search operation)

Get the specific blue-500 color (get-color operation)

Find the closest Tailwind colors for hex #FF5733 (find-similar operation)
check-contrast
Check the contrast ratio between white text and a blue background

Calculate WCAG compliance for #FF0000 text on #FFFFFF background
simulate-colorblind
Show how #FF6B6B appears to people with protanopia

Simulate all types of color blindness for the color blue
find-accessible-color
Find an accessible alternative to #FF0000 that works on white background

Get a darker version of #3498DB that meets WCAG AA standards on #F8F9FA
mix-colors
Mix red and blue in equal proportions

Blend #FF6B6B and #4ECDC4 with 30% of the second color using multiply mode

Tool Parameters

convert-color

  • input (required): The color value to convert
  • from (optional): Source format - if not specified, will auto-detect
  • to (optional): Array of target formats - if not specified, returns common formats (hex, rgb, hsl)

color-info

No parameters required - returns server information and examples

generate-harmony

  • baseColor (required): The base color to generate harmonies from (any supported format)
  • harmonyType (required): Type of harmony - complementary, analogous, triadic, tetradic, square, split-complementary, or double-complementary
  • outputFormat (optional): Format for output colors - defaults to hex
  • options (optional): Additional options:
    • angleAdjustment: Custom angle adjustment in degrees
    • analogousCount: Number of colors for analogous harmony (default: 3)
    • analogousAngle: Angle between analogous colors (default: 30)

convert-tailwind-color

  • input (required): The input to convert or search for
  • operation (required): Operation to perform:
    • to-hex or get-color: Convert Tailwind color name (e.g., "blue-500") to hex value
    • from-hex: Find exact Tailwind color name by hex value (e.g., "#3b82f6")
    • search: Search for colors by name (e.g., "blue")
    • get-all-shades: Get all shades of a color (e.g., "blue" returns blue-50 through blue-950)
    • find-similar: Find closest matching Tailwind colors for any hex value
  • outputFormat (optional): Format for output colors - defaults to hex

check-contrast

  • foreground (required): The foreground/text color (any supported format)
  • background (required): The background color (any supported format)

simulate-colorblind

  • color (required): The color to simulate (any supported format)
  • type (optional): Type of color blindness to simulate - if not specified, simulates all types
    • Options: protanopia, protanomaly, deuteranopia, deuteranomaly, tritanopia, tritanomaly, achromatopsia, achromatomaly

find-accessible-color

  • targetColor (required): The color to find an alternative for (any supported format)
  • backgroundColor (required): The background color to ensure contrast against (any supported format)
  • options (optional): Additional options:
    • targetContrast: Target contrast ratio (default: 4.5 for WCAG AA)
    • maintainHue: Try to maintain the original hue (default: true)
    • preferDarker: Prefer darker alternatives (default: auto-determined based on background)

mix-colors

  • color1 (required): First color to mix (any supported format)
  • color2 (required): Second color to mix (any supported format)
  • ratio (optional): Mix ratio (0-1). 0 = 100% color1, 1 = 100% color2, 0.5 = 50/50 mix (default: 0.5)
  • mode (optional): Blend mode (default: normal)
    • Options: normal (LAB space mixing), multiply, screen, overlay
  • outputFormat (optional): Format for output colors - if not specified, returns common formats (hex, rgb, hsl)

MCP Resources

The server provides the following resources that can be accessed via MCP ReadResource requests:

Available Resources

  1. color-palettes - List of all available color palettes

    • Returns metadata about all available palettes including name, version, and color count

  2. palette://material-design - Material Design color palette

    • Complete Material Design 3.0 color palette with 19 colors and their shades (50-900)

  3. palette://tailwind - Tailwind CSS color palette

    • Tailwind CSS v3.0 default palette with 22 colors and extended shades (50-950)

  4. palette://tailwind-v4 - Tailwind CSS V4 modernized color palette

    • Tailwind CSS v4.0 OKLCH-based palette with enhanced vibrancy and P3 color gamut support

  5. colors://named - CSS named colors organized by category

    • All 147 CSS named colors organized into categories like "Basic Colors", "Reds & Pinks", etc.

  6. colors://web-safe - Web-safe color palette

    • The 216 web-safe colors that display consistently across browsers, organized by hue

Resource Response Format

All resources return JSON data with application/json mime type. Example structures:

Palette Resource
{
    "name": "Material Design",
    "description": "Material Design color palette with primary colors and their shades",
    "version": "3.0",
    "colors": [
        {
            "name": "red",
            "shades": [
                { "name": "50", "value": "#ffebee" },
                { "name": "100", "value": "#ffcdd2" }
                // ... more shades
            ]
        }
        // ... more colors
    ]
}
Named Colors Resource
{
    "name": "CSS Named Colors",
    "description": "All CSS named colors organized by category",
    "totalColors": 147,
    "categories": [
        {
            "name": "Basic Colors",
            "description": "Fundamental color names",
            "colors": [
                { "name": "black", "hex": "#000000" },
                { "name": "white", "hex": "#ffffff" }
                // ... more colors
            ]
        }
        // ... more categories
    ],
    "allColors": [
        /* sorted list of all colors */
    ]
}

Example Requests

Convert with specific formats
{
    "input": "#D4C7BA",
    "to": ["rgb", "hsl", "hsb", "cmyk"]
}
Convert named color
{
    "input": "coral",
    "to": ["hex", "rgba", "hsla"]
}

Example Response

{
    "success": true,
    "input": "#D4C7BA",
    "detectedFormat": "hex",
    "hex": "#d4c7ba",
    "rgb": "rgb(212, 199, 186)",
    "hsl": "hsl(30, 23%, 78%)",
    "hsb": "hsb(30, 12%, 83%)",
    "cmyk": "cmyk(0%, 6%, 12%, 17%)"
}

Color Harmonies

The generate-harmony tool creates aesthetically pleasing color combinations based on color theory principles:

Harmony Types

  1. Complementary: Two colors opposite on the color wheel (180° apart)

    • High contrast, vibrant combinations
    • Example: Red (#FF0000) → Cyan (#00FFFF)

  2. Analogous: Adjacent colors on the color wheel

    • Harmonious, serene combinations
    • Default: 3 colors with 30° spacing
    • Customizable count and angle

  3. Triadic: Three colors evenly spaced (120° apart)

    • Vibrant yet balanced schemes
    • Forms an equilateral triangle on the color wheel

  4. Tetradic/Square: Four colors evenly spaced (90° apart)

    • Rich, diverse color schemes
    • Forms a square on the color wheel

  5. Split-Complementary: Base color + two adjacent to its complement

    • High contrast with more nuance than pure complementary
    • Default: ±30° from the complement

  6. Double-Complementary: Two complementary pairs

    • Complex, rich color schemes
    • Forms a rectangle on the color wheel

Example Harmony Requests

{
    "baseColor": "#FF6B6B",
    "harmonyType": "complementary",
    "outputFormat": "hex"
}

{
    "baseColor": "blue",
    "harmonyType": "analogous",
    "outputFormat": "rgb",
    "options": {
        "analogousCount": 5,
        "analogousAngle": 15
    }
}

Example Harmony Response

{
    "success": true,
    "input": "#FF6B6B",
    "harmonyType": "triadic",
    "outputFormat": "hex",
    "result": {
        "baseColor": "#ff6b6b",
        "colors": ["#ff6b6b", "#6bff6b", "#6b6bff"],
        "colorCount": 3,
        "description": "Three colors evenly spaced around the color wheel (120° apart), offering vibrant yet balanced schemes",
        "rawHSLValues": [
            { "h": 0, "s": 58, "l": 71 },
            { "h": 120, "s": 58, "l": 71 },
            { "h": 240, "s": 58, "l": 71 }
        ]
    }
}

Advanced Examples

Accessibility Tools

WCAG Contrast Checking
{
    "foreground": "#FF0000",
    "background": "#FFFFFF"
}

Response:

{
    "success": true,
    "foreground": "#FF0000",
    "background": "#FFFFFF",
    "contrastRatio": 3.998,
    "wcagCompliance": {
        "AA": {
            "normalText": false,
            "largeText": true
        },
        "AAA": {
            "normalText": false,
            "largeText": false
        }
    },
    "recommendation": "Increase contrast for better accessibility"
}
Finding Accessible Colors
{
    "targetColor": "#FF0000",
    "backgroundColor": "#FFFFFF",
    "options": {
        "targetContrast": 4.5,
        "maintainHue": true
    }
}
Color Blindness Simulation
{
    "color": "#FF6B6B",
    "type": "deuteranopia"
}

Response:

{
    "success": true,
    "originalColor": "#FF6B6B",
    "type": "deuteranopia",
    "simulatedColor": {
        "rgb": "rgb(181, 134, 107)",
        "hex": "#b5866b"
    },
    "info": {
        "name": "Deuteranopia",
        "description": "Complete absence of green cone cells",
        "prevalence": "1% of males",
        "severity": "Complete"
    }
}

Advanced Color Mixing

LAB Space Mixing (Perceptually Uniform)
{
    "color1": "#FF6B6B",
    "color2": "#4ECDC4",
    "ratio": 0.3,
    "mode": "normal"
}
Blend Mode Examples
{
    "color1": "#FF0000",
    "color2": "#0000FF",
    "ratio": 0.5,
    "mode": "multiply"
}

Scientific Color Spaces

LAB Color Space Conversion
{
    "input": "#FF6B6B",
    "to": ["lab", "xyz"]
}

Response:

{
    "success": true,
    "input": "#FF6B6B",
    "lab": "lab(62.85%, 47.38, 37.89)",
    "xyz": "xyz(36.48, 24.51, 12.19)"
}

Tailwind V4 Advanced Operations

Finding Similar Colors
{
    "input": "#FF5733",
    "operation": "find-similar"
}

Response:

{
    "success": true,
    "input": "#FF5733",
    "operation": "find-similar",
    "result": {
        "hexValue": "#FF5733",
        "exactMatch": false,
        "closestMatches": [
            {
                "tailwindName": "orange-500",
                "colorName": "orange",
                "shade": "500",
                "value": "#f97316",
                "distance": 0.12
            }
        ]
    }
}

Supported Color Formats

Input Formats

  • Hex: #RGB, #RGBA, #RRGGBB, or #RRGGBBAA (case-insensitive)
  • RGB: rgb(r, g, b) or r, g, b (values 0-255)
  • RGBA: rgba(r, g, b, a) (RGB values 0-255, alpha 0-1)
  • HSL: hsl(h, s%, l%) (h: 0-360, s/l: 0-100)
  • HSLA: hsla(h, s%, l%, a) (HSL values + alpha 0-1)
  • HSB/HSV: hsb(h, s%, b%) or hsv(h, s%, v%) (h: 0-360, s/b: 0-100)
  • CMYK: cmyk(c%, m%, y%, k%) (all values 0-100)
  • Named Colors: All CSS named colors (e.g., red, coral, dodgerblue)

Notes

  • HSB and HSV are treated as identical (they are the same color model)
  • CMYK conversion is simplified and not color-profile accurate
  • Auto-detection works for all supported format variations
  • Named colors are converted through their hex values
  • Alpha/transparency is preserved when converting between RGBA and HSLA
  • Extended hex formats support alpha channel (#RGBA → 4-digit, #RRGGBBAA → 8-digit)

MCP Resources

The server provides read-only resources for accessing color data:

Available Resources

  1. color-palettes - List of available color palettes

    • URI: color-palettes
    • Returns metadata about available palettes

  2. Material Design Palette - Google's Material Design colors

    • URI: palette://material-design
    • Returns 19 colors with shades (50-900)

  3. Tailwind CSS Palette - Tailwind's color system

    • URI: palette://tailwind
    • Returns 22 colors with shades (50-950)

  4. Named Colors - All CSS named colors organized by category

    • URI: colors://named
    • Returns 147 colors in 11 categories

  5. Web-Safe Colors - 216 web-safe colors

    • URI: colors://web-safe
    • Returns colors organized by hue groups

Accessing Resources in Claude

Get the Material Design color palette

Show me all CSS named colors

Get the Tailwind V4 color palette

Technical Details

Performance & Architecture

This MCP server is built with performance in mind:

  • Intelligent Caching: LRU cache for color conversion results to minimize computation
  • Lazy Loading: Modules are loaded on-demand to improve startup time
  • Optimized Algorithms: Pre-computed matrices and constants for color space transformations
  • Efficient Pattern Matching: Pre-compiled regex patterns for format detection

Error Handling

The server implements comprehensive error handling with:

  • Structured Error Responses: Machine-readable error codes and human-friendly messages
  • Actionable Suggestions: Each error includes specific suggestions for resolution
  • Context Preservation: Errors include relevant context about the operation that failed
  • Graceful Degradation: Non-critical failures don't crash the entire operation

Intelligent Defaults

When parameters are omitted, the server applies intelligent defaults:

  • Color Conversion: Returns hex, RGB, and HSL formats when no specific format requested
  • Color Mixing: Uses LAB color space for perceptually uniform results by default
  • Harmony Generation: Applies color theory best practices for each harmony type

Color Science

Advanced color science features include:

  • LAB Color Space: Perceptually uniform color mixing and transformations
  • XYZ Color Space: CIE tristimulus values for scientific color representation
  • Gamma Correction: Proper sRGB gamma handling for accurate conversions
  • D65 Illuminant: Standard illuminant for consistent color reproduction

License

Open sourced under the MIT license.