design-system-mcp

# design-system-mcp

An MCP server that gives coding agents ground truth about your React design system, and a linter they can run on their own UI.

[![CI](https://img.shields.io/github/actions/workflow/status/dgesteves/design-system-mcp/ci.yml?branch=main&style=flat-square&label=CI&labelColor=0d0f12)](https://github.com/dgesteves/design-system-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@dgesteves/design-system-mcp?style=flat-square&labelColor=0d0f12&color=22d3ee)](https://www.npmjs.com/package/@dgesteves/design-system-mcp)
[![License: MIT](https://img.shields.io/github/license/dgesteves/design-system-mcp?style=flat-square&labelColor=0d0f12&color=22d3ee)](LICENSE)

[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_server-0d0f12?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=design-system&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBkZ2VzdGV2ZXMvZGVzaWduLXN5c3RlbS1tY3AiLCItLXJvb3QiLCIke3dvcmtzcGFjZUZvbGRlcn0iXX0%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?style=flat-square)](https://insiders.vscode.dev/redirect/mcp/install?name=design-system&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40dgesteves%2Fdesign-system-mcp%22%5D%7D)
[![Claude Code plugin](https://img.shields.io/badge/Claude_Code-Plugin-d97757?style=flat-square&logo=claude&logoColor=white)](#claude-code-plugin)

<p align="center">
  <img src=".github/assets/hero.svg" width="100%" alt="An agent writes app/settings/danger-zone.tsx, calls check_ui, gets 8 errors and 3 warnings with fixes such as border-[#ef4444] to border-destructive and variant=danger to variant=destructive, applies them, and check_ui reports no problems.">
</p>

## The problem

Coding agents write UI from their training data, not from your design system. Ask for a settings card in a shadcn/ui project and you get `bg-[#ef4444]`, `p-[13px]`, a native `<button>` with hand-rolled classes, `variant="danger"` on a `Button` that only knows `destructive`, `<Card.Header>` in a system that exports `CardHeader`, and an icon button nobody can name with a screen reader.

The agent cannot see your Storybook or docs site, and TypeScript only catches part of it after the fact. On the demo draft above, `tsc` reports 3 of the 11 problems (the invalid variant, the unknown prop and the missing member) and has no opinion on hex colors, off-scale spacing, native elements or accessible names.

`design-system-mcp` reads your components, tokens and docs, and serves them to the agent over [MCP](https://modelcontextprotocol.io): what exists, which props and variant values are valid, which token to use. It also gives the agent `check_ui`, a linter it calls on its own output. Every finding has a rule id, a location and a concrete fix, so the agent can correct itself before you review anything.

## Does it help?

Claude Code built the same ten components for [vercel/ai-chatbot](https://github.com/vercel/ai-chatbot) with and without the [plugin](#claude-code-plugin), and `check` scored what it wrote:

| Model            | Clean without | Clean with the plugin | Design-system errors | Cost |
| ---------------- | ------------: | --------------------: | -------------------: | ---: |
| Claude Haiku 4.5 |        6 / 10 |           **10 / 10** |               13 → 0 | −11% |
| Claude Opus 5    |        8 / 10 |           **10 / 10** |                5 → 0 |  +7% |

The misses were raw colors for things the prompt described ("a red alert", "a green label"), a native `<label>` where the project has `Label`, and an icon button nobody could name with a screen reader. With the plugin, the agent looked components and tokens up before writing, and every run came out clean. It is one project and forty runs, so read it as a direction. The [method, per-run results and every generated file](bench/agents) are in the repository.

## On real codebases

Run as is, with no config, on public apps (with version 0.2.0). These counts are not a judgement of the teams: hardcoded values and unlabeled icon buttons slip through review everywhere, and agents copy what they see.

| Project                                                                   | Found with zero config                         | `check` findings                                                                                                                             |
| ------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [vercel/ai-chatbot](https://github.com/vercel/ai-chatbot) `c2f8235`       | `components.json` → 23 components, 52 tokens   | 77 in `app/` and `components/`: 41 raw colors, 20 native elements the design system wraps, 11 icon-only buttons without an accessible name   |
| [midday](https://github.com/midday-ai/midday) `5158731`, `apps/dashboard` | workspace package `@midday/ui` → 78 components | 1,237 in `src/`, including 105 icon-only buttons without an accessible name. Adopted with a [baseline](#adopting-it-in-an-existing-codebase) |
| [shadcn/ui](https://github.com/shadcn-ui/ui) website `0132174`            | custom `ui` alias → 66 components              | 115 in `app/` and `components/`, mostly raw colors                                                                                           |

## Quickstart

No config is needed in a shadcn/ui project (Tailwind v3 or v4), a monorepo whose components live in a workspace package, or the design-system package itself ([how it finds them](#zero-config)). Other layouts take a [config file](#configuration). Requires Node.js 22.18 or later.

**1. Give your agent the tools.** Pick one:

- **Claude Code**: install the [plugin](#claude-code-plugin), which brings the server, a skill that has Claude look components up before writing UI, and a hook that checks every UI file Claude writes:

  ```text
  /plugin marketplace add dgesteves/design-system-mcp
  /plugin install design-system@dgesteves
  ```

- **Cursor or VS Code**: click the install badge at the top, or add the [config](#cursor-and-vs-code) to the repository.
- **Any other MCP client**: run `npx -y @dgesteves/design-system-mcp` as a stdio server. There are [configs for Claude Desktop, Codex CLI, Zed and Gemini CLI](#other-clients).

**2. See what it found**, from the app's folder:

```sh
npx -y @dgesteves/design-system-mcp inspect
```

**3. Try it.** Ask your agent for some UI, such as _"Add a danger-zone card to the settings page."_ It looks the components, variants and tokens up before writing and runs `check_ui` on the result. In Claude Code the plugin's skill loads by itself for UI work (or run `/design-system:design-system`), and the hook checks each file as it is written.

**4. Check the codebase**, then add it to [CI](#ci):

```sh
npx -y @dgesteves/design-system-mcp check .
```

`check .` lints every `.tsx` and `.jsx` file under the folder, whatever the layout, and leaves out the design system's own components.

## Setup

The server speaks MCP over stdio. It finds the project from `--root`, a config file in the working directory, or the workspace roots the client reports, and otherwise uses the working directory.

### Claude Code plugin

The plugin bundles the server, a skill that tells Claude to look components and tokens up before writing UI, and a hook that runs `check` on every `.tsx`/`.jsx` file Claude writes or edits and hands the errors back, so they get fixed in the same turn instead of in review:

```text
/plugin marketplace add dgesteves/design-system-mcp
/plugin install design-system@dgesteves
```

```text
⏺ Write(app/promo/page.tsx)
  ⎿  PostToolUse hook: app/promo/page.tsx breaks the project's design system
     1:58 error [no-hardcoded-color] Hardcoded color `bg-[#f5f5f5]` → `bg-muted`.
     1:77 error [prefer-design-system-component] Native <button> where the design system has <Button>.
     …
⏺ The hook flagged five issues. Looking up Button and the color tokens before fixing.
⏺ design-system - get_component (MCP)(name: "Button")
⏺ Write(app/promo/page.tsx)   →   <Button variant="destructive"> on bg-muted, hook passes
```

The hook only speaks up about what Claude just changed: after an Edit it lists the findings on the edited lines and only counts older ones, it honours a [baseline](#adopting-it-in-an-existing-codebase), and it stays quiet in projects without a design system, so installing the plugin for every project is safe. Like `check`, it leaves the design system's own files alone: an edit to `components/ui/button.tsx` changes the design system, which is a call for you and your reviewers rather than a lint error. Warnings go to Claude as context without blocking. It runs the project's own install when there is one, else `npx`, and finds the project from the edited file, so it works in monorepos. If you added the server with `claude mcp add` before, remove that entry (`claude mcp remove design-system`) to avoid two copies of the tools.

### Cursor and VS Code

The badges at the top install the server in one click. To share it with the team, commit the config instead:

<details open>
<summary><strong>Cursor</strong></summary>

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "design-system": {
      "command": "npx",
      "args": ["-y", "@dgesteves/design-system-mcp", "--root", "${workspaceFolder}"]
    }
  }
}
```

</details>

<details open>
<summary><strong>VS Code (Copilot agent mode)</strong></summary>

`.vscode/mcp.json`:

```json
{
  "servers": {
    "design-system": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@dgesteves/design-system-mcp", "--root", "${workspaceFolder}"]
    }
  }
}
```

</details>

A client that passes `${workspaceFolder}` through unexpanded gets a warning on stderr, and the server falls back to the workspace r