Designrail MCP server reference
designrail mcp is a local Model Context Protocol server that exposes your project's DESIGN.md to coding agents. Register it with Claude Code, Cursor or any MCP client when you want the agent to look up tokens and component specs before writing UI, lint its own code before finishing, and score the page it built. It runs on your machine over stdio and reads DESIGN.md from disk on every call.
Install
The server ships in the designrail package (Node.js 20 or later); see the CLI reference for installation. You need a DESIGN.md first. Create one from a live site with:
pnpm dlx designrail scan https://www.example.com --site --install
Start the server by hand to check it runs. It waits for a client on stdin and exits when stdin closes:
pnpm dlx designrail mcp
| Flag | Default | What it does |
|---|---|---|
--design <file> |
DESIGN.md |
DESIGN.md to serve, resolved against the directory the server process starts in |
-h, --help |
Print usage and exit |
An unknown flag stops the server with exit code 2 before it starts listening.
If DESIGN.md is not at the root of the directory your client starts the server in, pass an absolute path to --design. The server starts even when the file is missing; each tool call then fails with "No DESIGN.md at <path>. Create one with designrail scan <url> --install, or pass --design."
Register with Claude Code
claude mcp add design-system -- pnpm dlx designrail mcp
To serve a DESIGN.md somewhere else, add the flag after the command:
claude mcp add design-system -- pnpm dlx designrail mcp --design /path/to/DESIGN.md
The Claude Code guide covers the full setup, including the skill file that scan --install writes.
Register with Cursor
Add the server to .cursor/mcp.json. The same JSON works for any client that takes an mcpServers config:
{
"mcpServers": {
"design-system": { "command": "pnpm", "args": ["dlx", "designrail", "mcp"] }
}
}
To pass a different file, append "--design", "/path/to/DESIGN.md" to args. See the Cursor guide for the matching Cursor rule.
Resource: design://DESIGN.md
| URI | Name | MIME type | Contents |
|---|---|---|---|
design://DESIGN.md |
design-md |
text/markdown |
The full DESIGN.md file: token front matter and usage rules |
Tool: get_tokens
Returns design tokens from the DESIGN.md front matter as JSON. Agents are told to call it before writing or changing UI so they reuse existing tokens.
| Input | Type | Required | What it does |
|---|---|---|---|
category |
colors, typography, spacing, rounded or components |
No | Return only this group; omit for all five |
A group missing from the file comes back as {}. When category is omitted or is spacing, and DESIGN.md contains the **Npx grid** sentence, the reply also states the grid rule. A trimmed reply for category: "spacing":
{
"spacing": {
"3xs": "2px",
"2xs": "4px",
"sm": "8px",
"xl": "16px"
}
}
followed by the line "Spacing grid: every margin, padding and gap is a multiple of 2px."
Tool: get_component
Returns the spec for one component: the tokens it uses plus its state variants.
| Input | Type | Required | What it does |
|---|---|---|---|
name |
string | Yes | Component name, for example button-primary, input or card |
The reply is a JSON object of every component whose key is name or starts with name- (so button-primary also returns button-primary-hover, button-primary-focus and so on), followed by the prose under the ### name heading in DESIGN.md when there is one. For an unknown name it lists the known components, leaving out -hover, -focus, -active and -disabled variants:
No component "nope". Known components: button-outline, button-primary, button-secondary, link, input, nav, image, card
Tool: check_snippet
Lints a CSS, Tailwind, JSX, Vue or Svelte snippet with the same rules as designrail lint-code: raw-color, token-literal, palette-class, off-grid and unknown-font. A line containing designrail-ignore is skipped.
| Input | Type | Required | What it does |
|---|---|---|---|
code |
string | Yes | The source code to check |
filename |
string | No | File name used to pick rules, for example Button.tsx or styles.css. Without it, the snippet is checked as snippet.css when it looks like CSS and as snippet.tsx otherwise |
The CSS-property rules (spacing in margin, padding and gap, and unknown-font) run when filename ends in .css, .scss, .sass, .less or .pcss, on <style> blocks when it ends in .vue, .svelte, .astro or .html, and on snippets without a filename that look like CSS: property: value; declarations inside braces, with no markup (<div), className=, arrow functions or import, export, return, const, let or function. Colour literals, Tailwind palette classes and arbitrary Tailwind spacing are checked in every snippet. Example reply:
3 issues against Stripe:
- line 1: #ff0000 is not in the Stripe palette.
- line 1: Tailwind default palette class "bg-blue-500" bypasses the design tokens; use a token class such as bg-primary.
- line 1: p-[13px] is off the 2px grid. Use {spacing.lg} 12px.
With no findings it replies "No design-system issues found against <name>."
Tool: check_url
Renders a URL in headless Chrome and compares every element with DESIGN.md, as designrail check does: off-palette colours, WCAG AA contrast failures, off-grid spacing, fonts, type sizes and radii.
| Input | Type | Required | What it does |
|---|---|---|---|
url |
string | Yes | Page to check, usually the local dev server, for example http://localhost:3000 |
The reply is Score <n>/100 (<checked> values checked). followed by the Markdown fix list, grouped by category with up to 12 items each and the token to use for every item. Compared with the CLI command, check_url checks one page, always in the light colour scheme. Bare URLs get a scheme the same way as in the CLI: http:// for localhost, 127.0.0.1, [::1], *.localhost and *.test, https:// for everything else, so localhost:3000 checks http://localhost:3000. It needs Chrome or Edge, found the same way as the CLI (CHROME_PATH overrides the search).
How DESIGN.md is read
- The path is fixed when the server starts:
--design, orDESIGN.mdin the server's working directory. - The file is read again on every tool call and resource read, so edits to DESIGN.md apply without restarting the server.
- Tokens come from the YAML front matter between the opening
---lines. Without front matter, or with front matter that is not a YAML mapping, every tool call returns an error result saying so, for example "<path>has no DESIGN.md front matter (a YAML block of tokens between --- lines at the top of the file)." Front matter withoutcolorsmakescheck_snippetandcheck_urlfail, whileget_tokensandget_componentreturn empty groups. - The spacing grid comes from the
**Npx grid**sentence that Designrail writes into DESIGN.md. Without it, the checks use the greatest common divisor of the spacing tokens.
To enforce the same rules in CI rather than in the agent loop, use the GitHub Action.
FAQ
Do I need to restart the server after editing DESIGN.md?
No. Every call reads the file again. Restart only to point --design at a different file.
Does the server send my code or DESIGN.md anywhere?
No. It runs locally over stdio, reads files from disk and, for check_url, renders the URL in a local headless browser.
Which tools work without Chrome?
get_tokens, get_component, check_snippet and the design://DESIGN.md resource only read the file. check_url needs Chrome or Edge.
Why does check_snippet miss off-grid padding in my CSS?
With a filename such as Button.tsx, the CSS-property rules don't run, because CSS-in-JS objects and inline styles aren't parsed as CSS. Pass filename: "styles.css" (or .scss, .less and so on) for stylesheet code, a .vue, .svelte or .astro name for single-file components with <style> blocks, or leave filename out and let the server detect plain CSS.