From one hex value to a full palette
Tailwind Shades is a VS Code extension, a command line tool and an MCP server that turn any color into a full 50 to 950 Tailwind palette. The MCP server, tailwindshades-mcp, exposes five tools plus one prompt, and runs either as a remote HTTP endpoint or as a local stdio process.
Put the cursor on #db4d53, name it brand, and Tailwind Shades writes a v4 @theme block running from brand-50 to brand-950 in OKLCH. That is the demo in the README, and the MCP server exposes the same engine to agents.
The repository is an npm workspace holding the VS Code extension, a palette engine with a CLI, the MCP server, and the website that also hosts the remote MCP endpoint.
How the shades are made
- It finds the Tailwind color closest to yours and copies how that color's lightness, saturation and hue change from light to dark.
- Your color stays exactly as given, at the shade where it fits best, so a light color can become 200 rather than always 500.
- The math runs in OKLCH, the color space Tailwind v4 uses, so steps look even to the eye.
Five tools and one prompt
The README says agents often guess Tailwind shades or add a single brand line instead of a palette. The server gives them generate_palette, find_closest_tailwind_color, get_tailwind_palette, list_tailwind_colors and convert_color, plus an add_brand_color prompt.
Remote or local
The remote endpoint needs nothing installed. The local option runs tailwindshades-mcp over stdio through npx. The README gives a command for one agent CLI and config blocks for Cursor and VS Code, and lists the server in the MCP Registry with both options.
Versions it understands
The palette tooling covers Tailwind v4, v3, v2 and v1. V4 and v3 get shades 50 to 950, v2 gets 50 to 900, and v1 gets 100 to 900, each against that version's own default palette. See Tailwind design system for token structure.
Use it with UiChemy
Tailwind Shades produces palettes, not pages. Its CLI can output plain CSS variables, and you can choose to carry them into the custom CSS of a page built in UiChemy Composer, which writes real HTML, CSS and JS inside Elementor or Gutenberg. Get Started at uichemy.com. For color thinking, see color system, better colors and design tokens.
Connect Tailwind Shades MCP Server for Color Palettes to your AI client
claude mcp add --transport http --scope user tailwindshades https://tailwindshades.bourhaouta.com/mcpConnect the remote server
In Claude Code, run
claude mcp add --transport http --scope user tailwindshades https://tailwindshades.bourhaouta.com/mcp. Nothing needs installing locally.Configure Cursor or VS Code
For Cursor, put the JSON above in ~/.cursor/mcp.json or .cursor/mcp.json. For VS Code, use .vscode/mcp.json with a servers entry of type http and the same URL.
Run it locally instead
Use
npx -y tailwindshades-mcpas a stdio server, for exampleclaude mcp add --scope user tailwindshades -- npx -y tailwindshades-mcp.Ask for a palette
Try the README example: add a brand color #db4d53 to my theme. The agent should call the palette tools rather than guess shades.
Client configuration
{
"mcpServers": {
"tailwindshades": { "url": "https://tailwindshades.bourhaouta.com/mcp" }
}
}Endpoints and ports
https://tailwindshades.bourhaouta.com/mcpHTTP endpoint, nothing to installhttps://tailwindshades.bourhaouta.comTry the palettes in the browserio.github.bourhaouta/tailwindshadesListed with both remote and local optionsWhat you can do with it
- Palette from any colorThe extension accepts hex, rgb, hsl, oklch or a CSS color name and writes a full shade scale under a name you pick, such as brand.
- Closest Tailwind colorfind_closest_tailwind_color maps a color to the nearest class, for example #db4d53 to red-500, and reports whether the difference is visible.
- Tailwind's own defaultsget_tailwind_palette returns the default colors exactly as Tailwind defines them, so agents do not write values like slate-500 from memory.
- Color conversionconvert_color turns any color into oklch(), hex and rgb, the first being what Tailwind v4 uses.
- Version detectionThe extension detects the Tailwind version from package.json, CSS hints or a config file, and falls back to v4 when nothing is found.
- Output choices in the CLIThe CLI supports theme, config, css, live and shopify outputs. Live writes CSS where every shade follows one variable, for colors chosen at runtime.
- Remote endpointA hosted MCP endpoint means there is nothing to install. A local stdio server is the alternative for those who prefer a process on their own machine.
- add_brand_color promptA bundled prompt that the README says appears as a slash command in at least one agent. The README example is a request to add a brand color to a theme.
Tools it exposes
generate_palette
Generates a palette with the same code as the extension, for the project's Tailwind version.
find_closest_tailwind_color
Finds the Tailwind class closest to a color, such as red-500 for #db4d53, and says whether the difference is visible.
get_tailwind_palette
Returns Tailwind's own default colors exactly as Tailwind defines them, such as slate-500.
list_tailwind_colors
Lists the names of Tailwind's default colors for a given version.
convert_color
Converts any color to oklch(), hex and rgb.
Frequently asked questions
What is the Tailwind Shades MCP server?
It is the tailwindshades-mcp package from the vscode-tailwindshades repository. It gives AI agents five tools for generating palettes, matching Tailwind colors, reading default colors, listing color names and converting colors, plus an add_brand_color prompt.
Should I use the remote or the local server?
Use the remote endpoint when you want nothing to install, since you only point your client at the URL. Use the local stdio server, run through npx, when you prefer a process on your own machine. The README documents both.
Which Tailwind versions are supported?
Tailwind v4, v3, v2 and v1. Shades run 50 to 950 for v4 and v3, 50 to 900 for v2 and 100 to 900 for v1. Colors are OKLCH for v4 and hex for earlier versions, unless you choose another format.
Does it keep my original color?
Yes. The README says your color stays exactly as it is, placed at the shade where it fits best. The other shades follow how the closest Tailwind color changes in lightness, saturation and hue, calculated in OKLCH.
Does it work outside VS Code?
Yes. The same palettes come from a command line tool, run with npx tailwindshades-cli, and from the MCP server. The extension also publishes to Open VSX for Cursor, Windsurf and VSCodium, and there is a browser demo.
Which agents can connect to it?
The README gives a Claude Code command, a Cursor config and a VS Code config, and says setup for each agent is in the package README. Any MCP client that supports HTTP or stdio servers should be able to connect.
Is it free and open source?
The repository is MIT licensed, with the copyright held by Omar Bourhaouta. The README does not mention a paid tier for the extension, the CLI or the MCP server, so treat all three as free to use under that licence.