# PickShade MCP server

Color tools for AI assistants: convert any color, find colors by name, check and fix WCAG 2 and APCA contrast, audit palettes for accessibility and color blindness, build gradients, scales and full design systems, export tokens for CSS, Tailwind v4, SCSS and DTCG.

All math follows CSS Color 4 (OKLCH, OKLab, Display P3, Rec. 2020) and runs locally and deterministically. No API key, no account, no telemetry.

Website and docs: [pickshade.com/mcp](https://pickshade.com/mcp)

## Use the hosted server

No install. Streamable HTTP endpoint:

```
https://pickshade.com/api/mcp
```

Claude Code:

```bash
claude mcp add --transport http pickshade https://pickshade.com/api/mcp
```

Cursor, VS Code and other clients that read `mcpServers`:

```json
{
    "mcpServers": {
        "pickshade": { "url": "https://pickshade.com/api/mcp" }
    }
}
```

## Run locally over stdio

```json
{
    "mcpServers": {
        "pickshade": { "command": "npx", "args": ["-y", "@pickshade/mcp"] }
    }
}
```

Requires Node.js 20 or newer.

## Tools

Every tool accepts colors as HEX, `rgb()`, `hsl()`, `oklch()`, CSS names like `navy`, common names like `royal blue` or `бордовый`, and Tailwind classes like `sky-500`.

| Tool              | What it does                                                                                             |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| `parse_color`     | Every format, the closest name and Tailwind class, gamut and the better text color for any color         |
| `convert_color`   | HEX, RGB, HSL, HSV, HWB, CMYK, Lab, LCH, OKLab, OKLCH, Display P3, Rec. 2020, XYZ, SwiftUI, Flutter      |
| `find_colors`     | Turns words like "sage" or "dusty rose" into real HEX values                                             |
| `check_contrast`  | WCAG 2 ratio with AA and AAA levels, and APCA Lc with the usage it allows                                |
| `fix_contrast`    | The closest color that reaches a contrast target, changing only OKLCH lightness so the hue stays         |
| `audit_palette`   | Checks every text and background pair, color blindness conflicts and out-of-gamut colors in a palette    |
| `check_gamut`     | Whether a color fits sRGB, Display P3 and Rec. 2020                                                      |
| `nearest_names`   | Closest named colors, CSS keywords and Tailwind classes by perceptual distance                           |
| `compare_colors`  | CIEDE2000 and deltaE OK difference with a plain verdict, lightness, chroma and hue shift                 |
| `generate_scale`  | An 11-step 50–950 scale in OKLCH with even perceived lightness, the shape of Tailwind palettes           |
| `tints_shades`    | Tints, shades and tones of a color                                                                       |
| `harmonies`       | Complementary, split-complementary, analogous, triadic, tetradic, square and monochromatic in OKLCH      |
| `mix_colors`      | Mixes two colors in a chosen space, like CSS `color-mix()`                                               |
| `make_gradient`   | CSS gradients interpolated in OKLab or OKLCH, without the gray middle                                    |
| `generate_palette`| Harmonious palettes in OKLCH, repeatable with a seed                                                     |
| `simulate_cvd`    | Protanopia, deuteranopia, tritanopia and achromatopsia, with pairs that become hard to tell apart        |
| `export_tokens`   | CSS variables, Tailwind v4 `@theme`, SCSS, JSON, DTCG tokens, JS arrays or an SVG swatch strip           |
| `build_system`    | A full color system from one brand color: scales, light and dark roles, shadcn/ui and Tailwind export    |

## Prompts

- `accessible_theme`: light and dark themes from a brand color with every text pair checked
- `audit_colors`: readable pairs, color blindness conflicts and gamut for a list of colors
- `describe_color`: a color explained in plain words with its values, name, contrast and matches

## REST API

The same tools over HTTP, JSON in and out: [pickshade.com/api](https://pickshade.com/api), OpenAPI 3.1 at `https://pickshade.com/api/v1/openapi.json`.

## What is inside

| Package | Purpose |
| --- | --- |
| `packages/color` | Color math: parsing every CSS color syntax, conversions between sRGB, Display P3, Rec. 2020, Lab, LCH, OKLab and OKLCH, gamut mapping, WCAG 2 and APCA contrast, CIEDE2000 and deltaE OK, scales, harmonies and color vision simulation |
| `packages/data` | Color names (CSS keywords, common names in 30 languages, an extended list), the Tailwind CSS palette |
| `packages/exports` | Code generators: CSS variables, Tailwind v4 `@theme`, SCSS, JSON, DTCG tokens, SVG |
| `packages/tools` | The 18 tools with their input schemas, shared by the MCP server and the REST API |
| `packages/mcp` | The MCP server (`@pickshade/mcp`) |

## Develop

```bash
pnpm install
pnpm check
pnpm build
```

The bundled server is written to `packages/mcp/dist`.

## License

MIT. Color names include data from [meodai/color-names](https://github.com/meodai/color-names) (MIT); Tailwind palette values are from [Tailwind CSS](https://tailwindcss.com) (MIT).