Tailwind Shades

tailwindshades-mcp

An MCP server that gives AI agents real Tailwind CSS palettes, so they stop guessing shades. Works with Tailwind v4, v3, v2 and v1.

Ask your agent "Add a brand color #db4d53 to my theme", and it writes a full 50 to 950 palette in the project's Tailwind format, with #db4d53 exactly at brand-500. Same engine as the Tailwind Shades editor extension and tailwindshades.bourhaouta.com.

Setup

Remote (nothing to install)

Connect your agent to https://tailwindshades.bourhaouta.com/mcp (Streamable HTTP, no API key).

Claude Code

claude mcp add --transport http --scope user tailwindshades https://tailwindshades.bourhaouta.com/mcp

Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project)

{
  "mcpServers": {
    "tailwindshades": { "url": "https://tailwindshades.bourhaouta.com/mcp" }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "tailwindshades": { "type": "http", "url": "https://tailwindshades.bourhaouta.com/mcp" }
  }
}

Local (stdio)

Runs on your machine with npx, so nothing leaves it. Needs Node.js 20 or later.

Claude Code

claude mcp add --scope user tailwindshades -- npx -y tailwindshades-mcp

Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project)

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

VS Code (.vscode/mcp.json)

{
  "servers": {
    "tailwindshades": { "command": "npx", "args": ["-y", "tailwindshades-mcp"] }
  }
}

Other agents: use the URL above, or run npx -y tailwindshades-mcp as a stdio server. It's also in the MCP Registry as io.github.bourhaouta/tailwindshades.

Tools

All five tools are read-only.

generate_palette

A full palette from one color, ready to paste.

Input	Default
color	required: any CSS color (#db4d53, rgb(), hsl(), oklch(), a name)
name	the closest Tailwind color, which replaces Tailwind's own palette, so the tool warns
tailwindVersion	4 (also 3, 2, 1)
format	oklch for v4, hex before (also rgb)
output	theme for v4, config before (also css, and live and shopify for v4)
plain, semantic	false: with live or shopify, a plain :root block instead of @theme, and a --color-<name>-foreground

live is for colors picked at runtime (a user, a tenant, a CMS setting): CSS where every shade follows one variable, rebuilt in the browser. shopify adds the color setting and Liquid line for Shopify themes, where the merchant picks the color in the theme editor. See Colors picked at runtime.

Returns the code, plus the shades, the shade that holds the input color and the closest Tailwind color as structured data.

The code starts with a comment of readable pairs: text and background classes that pass WCAG AA (4.5:1), tested on the real shades. Agents use them for buttons and text, so a red brand gets bg-brand-600 text-white instead of the failing bg-brand-500 text-white:

/* Readable pairs (WCAG AA, 4.5:1 or more):
   button     bg-brand-600 text-white      5.09:1
   text       bg-white text-brand-600      5.09:1
   badge      bg-brand-100 text-brand-700  5.43:1
   dark mode  bg-brand-950 text-brand-400  5.33:1
   avoid      bg-brand-500 text-white      4.03:1 */

find_closest_tailwind_color

The Tailwind shade that looks most like a color, e.g. #db4d53 → red-500, with Tailwind's value, the distance, and whether the difference is visible. Agents use it to pick an existing class instead of an arbitrary value, or to decide a custom palette is needed.

get_tailwind_palette

Tailwind's own default colors, exactly as Tailwind defines them: a whole color (blue) or one shade (slate-500), for Tailwind v4, v3, v2 or v1. Values are oklch() in v4 and hex before. Agents use it instead of writing Tailwind's default values from memory.

list_tailwind_colors

The names of Tailwind's default colors for a version (26 in v4, including mauve, olive, mist and taupe), with the shades they have and each one's 500 value as a sample.

convert_color

Any CSS color as oklch(), hex and rgb, formatted like Tailwind. Handy when a project on Tailwind v4 needs one oklch() value rather than a whole palette.

Prompt

add_brand_color

Arguments: color and an optional name (default brand). It asks the agent to find the project's Tailwind version, call generate_palette, and paste the code into the theme. Clients like Claude Code show it as a slash command.

Host it yourself

The package also exports createServer(), a fresh McpServer with all its tools and the prompt. Serve it with the MCP TypeScript SDK, for example over HTTP in any web-standard runtime (this is how the remote server above runs, as a Next.js route):

import { createMcpHandler } from '@modelcontextprotocol/server'
import { createServer } from 'tailwindshades-mcp'

const handler = createMcpHandler(createServer)

export const POST = (request: Request) => handler.fetch(request)

More

• tailwindshades-cli: the same palettes from the command line
• Source and issues

License

MIT © Omar Bourhaouta