tailwind-mcp

A Model Context Protocol server that asks Tailwind itself. No hand-written class lists, no stale snapshots — the server loads your project's own tailwindcss and queries the real engine, so every answer matches the code you actually build.

Why this exists

An LLM writing Tailwind makes three mistakes, all of them the same mistake: it invents classes that do not exist.

<div class="bg-gray-600 p-4 shadow-lg">
  <!-- does this class exist in THIS project? -->
  <div class="bg-red-550 mt-[16px]">
    <!-- typo, and a magic number instead of a token -->
    <div class="p-2 p-4 text-sm text-lg"><!-- which of these two actually wins? --></div>
  </div>
</div>

Every existing "Tailwind MCP" answers this by shipping a class list copied from a documentation snapshot. That list is wrong the moment you use a custom theme, a plugin, or a version newer than the copy — and it cannot tell you which of two conflicting classes wins, because that depends on your project's own configuration.

This server has no list. It loads the tailwindcss package from your node_modules and asks the engine:

your project → your tailwindcss → the real engine → the real answer

• the class list contains exactly the utilities your project can build, including custom theme values, @utility blocks and plugin classes;

• the version is yours, so v3 and v4 projects each get the truth for their own generation;

• which class wins a conflict is decided by Tailwind's own class order, not by a guess;

• when you edit your config, the server notices and rebuilds itself — no restart.

Related MCP server: TailwindCSS MCP Server

Install

Requires Node.js ≥ 20.

git clone https://github.com/vitkuz573/tailwind-mcp.git
cd tailwind-mcp
npm ci
npm run build

Connect a host

OpenCode

opencode mcp add tailwind -- node /absolute/path/to/tailwind-mcp/dist/index.js

Or by hand:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "tailwind": {
        "type": "local",
        "command": ["node", "/absolute/path/to/tailwind-mcp/dist/index.js"],
        "timeout": { "startup": 60000, "execution": 120000 },
      },
    },
  },
}

The server finds the project by walking up from its working directory until it finds a node_modules/tailwindcss. Every tool also takes an optional project argument with an absolute path, for when the Tailwind project is not the current directory.

Claude Code

claude mcp add tailwind -- node /absolute/path/to/tailwind-mcp/dist/index.js

Any other MCP client

node dist/index.js                 # stdio transport

The tool surface

tailwind_diagnose — start here

One call, every problem with a class list.

{ "candidates": ["p-4 flex bg-red-501 mt-[16px] p-2 p-4 shadow-sm"] }

Suggestions come from the real class list, so a missing shade is completed too: bg-brand becomes bg-brand-500 when your project defines that scale.

The rest

Details worth knowing

Which class wins. Tailwind sorts the utilities it generates, and at equal specificity the later rule wins. The server asks the engine for that order rather than guessing, so p-4 beating p-2 is a fact, not a heuristic. Shorthands are expanded, so p-4 and pl-2 are correctly seen to fight over the left padding.

The v3 trap. In v4 the whole shadow, radius and blur scale shifted. shadow-sm still exists — and now means what shadow-xs used to mean. The server flags that as meaning-changed, because the class compiles and the bug is silent.

Contrast. Tailwind v4 stores colours as oklch(). The server converts to sRGB following CSS Color 4, including the chroma reduction needed for colours outside the sRGB gamut, and reports the WCAG AA and AAA verdicts.

Reloading. The set of files that feed the design system is discovered by following @import, @config and @plugin, and a size/mtime fingerprint of those files decides whether the engine has to be rebuilt. Edit any of them and the next call sees the change.

Package imports. A real stylesheet imports more than itself: the framework's own sheet, packages that ship utilities (tw-animate-css), and sub-paths of packages (shadcn/tailwind.css). All three are resolved through the package's exports map, preferring the style condition, and plugins are loaded from packages too (@plugin "@tailwindcss/typography"). Nothing has to be rewritten or stubbed out.

Performance

Measured against a real project with a custom theme, on the first call after a server start:

There is no network call, no database and no cache to go stale. The engine is rebuilt when your configuration changes, so the first call after an edit pays the reload cost once.

Tailwind's own canonicalizeCandidates is deliberately not used: it builds an index of every class on first use, which takes seconds and blocks the event loop. The same two rules are applied locally against your theme instead, which answers in milliseconds.

Development

npm run verify   # format check, typecheck, tests, build
npm test         # vitest
npm run inspect  # MCP inspector

The tests run against real Tailwind installations in temporary project fixtures — v3 and v4, with custom themes, TypeScript configs and plugins. Nothing is mocked.

Status

Tailwind Labs does not ship an official Tailwind MCP server. This is an independent implementation built on the official MCP SDK and Tailwind's own public engine API.

License

MIT