color-engine MCP Server

A Model Context Protocol (MCP) server providing 6 CSS color utilities: parsing, conversion, gamut mapping, WCAG contrast (with optional APCA), tint/shade ramp generation (with optional design-token output), and contrast-target solving. All tools operate purely in-memory — no network I/O, no filesystem writes.

All JSON outputs shown in this README are genuine responses captured from the built server via the MCP Inspector CLI (npx @modelcontextprotocol/inspector --cli).

Installation

Requires Node.js >= 20. The npm package exposes a color-engine-mcp bin, so no clone or build is needed — clients launch it via npx. This is a standard stdio MCP server using only the tools primitive, so any MCP-compatible client registers it the same way: point the client at the launch command, and the client spawns and manages the process itself.

For Claude Code, one command registers the server:

claude mcp add color-engine -- npx -y color-engine-mcp

(The default scope is the local project; add --scope user to register it for all your projects, or --scope project to write the shared .mcp.json.)

Most other JSON-configured clients accept this shape verbatim:

{
  "mcpServers": {
    "color-engine": {
      "command": "npx",
      "args": ["-y", "color-engine-mcp"]
    }
  }
}

Where the entry lives in a few common clients:

Other clients (Zed, JetBrains, custom agents built on an MCP SDK, …) differ only in the file location and occasionally the top-level key name — see their MCP server registration docs.

Listed in the official MCP Registry as io.github.aimsise/color-engine-mcp.

Once connected, try asking your agent things like:

• "Generate an 11-step Tailwind ramp from #3b82f6"
• "Find an accessible text color for background #1e293b at 4.5:1 contrast"

To run from a clone instead, see Development.

Color input handling

Every tool routes color strings through one shared parse boundary, so the rules below apply uniformly.

Accepted formats. Any CSS color string culori can parse, including named colors, hex (#rgb, #rgba, #rrggbb, #rrggbbaa), rgb()/rgba(), hsl()/hsla(), and oklch() — plus the wide-gamut / CSS Color 4 formats:

• color(display-p3 r g b)
• lab(L a b) / lch(L C h)
• oklab(L a b)
• hwb(h w b)
• color(rec2020 r g b)
• color(a98-rgb r g b)
• color(xyz-d65 x y z)

A wide-gamut input outside sRGB parses fine and reports inGamut: false:

{ "input": "color(display-p3 1 0 0)" }

{
  "hex": "#ff0000",
  "rgb": { "r": 255, "g": 0, "b": 0 },
  "oklch": { "l": 0.6485740751442981, "c": 0.2994852863383699, "h": 28.958132730803953 },
  "inGamut": false
}

Whitespace. Leading/trailing whitespace is trimmed before parsing — " #ff0000 " parses as #ff0000.

CSS Color 4 channel clamping (legacy spaces only). Out-of-range channels in hex / rgb() / hsl() inputs are clamped at the parse boundary, per CSS Color 4: rgb(-50 0 0) behaves exactly as rgb(0 0 0), and hsl() saturation/lightness clamp likewise (hue wraps). Inputs in other modes (oklch(), lab(), color(display-p3 …), …) are not clamped — their out-of-gamut values flow through raw, which is what makes gamut_map useful.

none channels. CSS Color 4 none channels are normalized to 0 in all six tools — oklch(0.5 none 30) behaves exactly as oklch(0.5 0 30).

Component magnitude. A parseable component with an absurd magnitude (above 1e6, e.g. oklch(0.5 1e30 30)) is rejected with COMPONENT_OUT_OF_RANGE — two tools (gamut_map, solve_for_contrast) surface it differently; see the error codes table. Real out-of-gamut values are many orders of magnitude below this guard and are never affected.

Alpha policy. contrast and solve_for_contrast reject translucent colors — any explicit alpha < 1, including rgba()/hsla() functional alpha and 4-/8-digit hex (#00000080) — with ALPHA_UNSUPPORTED, because the effective color of a translucent layer depends on an unknown backdrop; composite over the backdrop first. All other tools accept translucent input and simply ignore the alpha channel (computations use the opaque color; no output ever carries an alpha component).

Length cap. Color strings longer than 256 characters (after trimming) are rejected with INPUT_TOO_LONG.

Tools

parse_color

Parse any CSS color string and return hex, RGB, OKLCH, and gamut info.

Input schema

Output for { "input": "#ff0000" }

{
  "hex": "#ff0000",
  "rgb": { "r": 255, "g": 0, "b": 0 },
  "oklch": { "l": 0.6279553639214311, "c": 0.2576833038053608, "h": 29.233880279627854 },
  "inGamut": true
}

The rgb channels are the sRGB-clamped 0–255 integer projection (consistent with hex). For an out-of-gamut input (e.g. a wide-gamut oklch(...)), the channels are clamped into [0, 255] rather than reporting raw out-of-range values — use the inGamut flag to detect that the input fell outside sRGB. The oklch block, by contrast, is the raw (lossless, unrounded) OKLCH of the input, and oklch.h is 0 for achromatic colors.

convert_color

Convert a CSS color string into a canonical hex, rgb, hsl, or oklch format string.

Input schema

Output for { "input": "#ff0000", "to": "oklch" }

{ "result": "oklch(0.62796 0.25768 29.23)" }

Raw vs. clamped for out-of-gamut inputs

For a color that lies outside the sRGB gamut, the target formats diverge:

• to: "oklch" returns the raw, lossless OKLCH triple, so an out-of-gamut color round-trips faithfully. E.g. { "input": "oklch(0.7 0.4 30)", "to": "oklch" } → "oklch(0.70000 0.40000 30.00)".
• to: "hex", "rgb", and "hsl" are all derived from the sRGB-clamped projection and report the in-gamut approximation. E.g. { "input": "oklch(0.7 0.4 30)", "to": "rgb" } → "rgb(255, 0, 0)". rgb channels are integers in [0, 255].

(L/C are formatted to 5 decimal places and H to 2, which guarantees an exact hex round-trip across the full sRGB cube.)

contrast

Compute the WCAG 2.1 contrast ratio between two fully opaque CSS color strings and return tier flags. Optionally also computes the APCA Lc value (see APCA).

Input schema

Output for { "a": "#000000", "b": "#ffffff" }

{
  "ratio": 21,
  "aaNormal": true,
  "aaLarge": true,
  "aaaNormal": true,
  "aaaLarge": true
}

ratio is the 2-decimal display value. The four tier booleans are derived from the unrounded raw ratio (so a near-boundary raw 4.4999, which displays as 4.50, still yields aaNormal: false).

WCAG 2.1 tier thresholds:

• aaNormal / aaLarge require ratio ≥ 4.5 / ≥ 3.0
• aaaNormal / aaaLarge require ratio ≥ 7.0 / ≥ 4.5

Errors. A string that fails to parse yields a parameter-named error — PARSE_FAILED: could not parse the foreground color for a, PARSE_FAILED: could not parse the background color for b. Translucent input yields ALPHA_UNSUPPORTED (see Alpha policy).

APCA (optional perceptual contrast)

Pass apca: true to additionally get apcaLc — the signed APCA-W3 (SAPC-4g) lightness contrast Lc, rounded to 2 decimals, for text a over background b (the argument order matters for APCA, unlike the symmetric WCAG ratio). The sign encodes polarity: positive for dark text on a light background, negative for light text on a dark background; compare magnitudes with |Lc|.