ux-mcp — Claude Code command: what it does, how to install
The ux-mcp command starts the ux-skill engine as an MCP server over stdio, exposing 25 tools for recommendations, linting, and design-system work.
MIT ★ 110 updated 2026-11-02
/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skillWhat ux-mcp does
Running ux-mcp (or python3 -m engine.mcp.server) launches a server that exchanges JSON-RPC over stdio and writes logs to stderr only, leaving stdout clean for the protocol. The tool set covers ux_recommend and ux_lint for style suggestions and anti-pattern checks, read access to the data manifests (styles, palettes, type pairs, components, brand specs, anti-patterns), saving and loading .ux/design-system/MASTER.md, and a group of tools for detecting, measuring, extending and exporting a design system a project already has.
The MCP transport ships as a separate dependency: install it with pip install 'uxskill[mcp]', or with pip install 'mcp>=1.0' if uxskill is already present. Claude Desktop, Cursor and Windsurf each pick it up through their own config file — claude_desktop_config.json or mcp.json — pointing at the ux-mcp command.
Inside Claude Code with the plugin installed, the slash commands talk to the engine directly, so this MCP layer stays unused there.
What it helps with
- wire the ux-skill engine into Cursor, Windsurf or Claude Desktop without installing the plugin
- pull style, palette and type-pair recommendations through an MCP call
- run the anti-pattern linter against project paths
- save and reload
.ux/design-system/MASTER.md - detect and extend a design system a project already has
Example prompts for the agent
- Start
ux-mcpand register it as an MCP tool in Cursor - Call
ux_recommendwith a brief for a Next.js landing page - Run
ux_lintover thesrc/componentsfolder through MCP
How to install ux-mcp
1Plugin marketplace
/plugin marketplace add Laith0003/ux-skill/plugin install ux@ux-skill2Manually: put the files in place
.claude/commands/ux-mcp.mdCall it with /ux-mcp. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/ux-mcp.mdCall it with /prompts:ux-mcp. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/ux-mcp.prompt.mdManually: put the files in place
.gemini/commands/ux-mcp.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about ux-mcp
How to install ux-mcp in Claude Code?
Run /plugin marketplace add Laith0003/ux-skill first, then /plugin install ux@ux-skill; the command then exists as the file .claude/commands/ux-mcp.md.
What does ux-mcp do?
It runs the ux-skill engine as a stdio MCP server, exposing 25 tools — a recommender, a linter, data manifests, and design-system utilities — to any MCP client without needing the plugin installed.
Do I still need the ux-skill plugin in Claude Code once the server is running?
No: with the plugin installed, its slash commands hit the engine directly and the MCP transport goes unused there. It matters for other hosts, like Cursor, Windsurf or Claude Desktop.
Source text
ux-mcp.md · MIT
---
name: ux-mcp
description: Run the ux-skill engine as a Model Context Protocol server over stdio. Exposes 25 tools (recommender, linter, MASTER.md persistence, the data manifests, the foundations engine, and the tools that read, measure, extend and export a design system a project already has) so any MCP-capable client (Claude Desktop, Cursor, Windsurf, generic agents) can query the engine without installing the full plugin.
allowed-tools: Bash
disable-model-invocation: false
---
# /ux-mcp — the design intelligence MCP
**One server. Twenty-five tools. Every MCP-aware client gets the engine.**
This is the asymmetric move. None of the leading Claude UX skills (ui-ux-pro-max-skill, open-design, taste-skill, huashu-design, stitch, nothing-design, hallmark, material-3) ship an MCP server. Doing so turns ux-skill into the canonical *design-intelligence MCP* — agents in any host can call into the same recommender, linter, and manifests that the plugin uses, without needing to install the plugin itself.
## When to use
- You're using **Cursor**, **Windsurf**, **Claude Desktop**, or any other MCP-capable host and want ux-skill available without forcing the host to learn the plugin layout.
- You're orchestrating a **multi-agent pipeline** and need a single source of truth for design constraints across agents.
- You're writing **CI tooling** that calls the recommender or linter from a long-running daemon rather than spawning a CLI each time.
## When to skip
- You're already inside Claude Code with the plugin installed — the slash commands hit the engine directly, no MCP transport needed.
- You only need a one-shot recommendation or lint — `ux recommend` / `ux lint` from the CLI is simpler.
## Install
The MCP transport is an **optional dependency** to keep the base install slim:
```bash
pip install 'uxskill[mcp]'
```
Or, if you already have `uxskill`:
```bash
pip install 'mcp>=1.0'
```
## Start the server
```bash
ux-mcp # entry point (preferred — wired by pyproject.toml)
python3 -m engine.mcp.server # equivalent module form
```
The server speaks stdio JSON-RPC. Logs go to **stderr only**; stdout is reserved for the protocol stream.
## Exposed tools (25)
| Tool | What it does |
|---|---|
| `ux_recommend` | Run the 5-parallel-search recommender over a brief. Returns style + palette + type pair + motion + components + brand exemplars + guardrails + rationale. |
| `ux_lint` | Run the anti-AI-slop regex linter over paths. Returns findings with rule id, severity, file, line, excerpt, fix. |
| `ux_styles` | Return all 84+ entries from `data/styles.json`. |
| `ux_palettes` | Return all 176+ entries from `data/palettes.json`. Optional `mode` filter (`light` / `dark`). |
| `ux_type_pairs` | Return all 70+ entries from `data/type-pairs.json`. |
| `ux_components` | Return all 148+ entries from `data/components.json`. Optional `category` filter. |
| `ux_industries` | Return all 184+ entries from `data/industries.json`. Optional `category` filter. |
| `ux_motion_presets` | Return all 57+ entries from `data/motion-presets.json`. Optional `category` filter. |
| `ux_anti_patterns` | Return all 35+ regex rules from `data/anti-patterns.json`. Optional `severity` filter. |
| `ux_brands` | Return all 92 brand specs from `data/brands/*.json` (Apple, Stripe, Linear, Tesla, Notion, etc.). Optional `category` filter. |
| `ux_landing_patterns` | Return all 24+ entries from `data/landing-patterns.json`. Optional `category` filter. |
| `ux_persist_save` | Persist a recommendation as `.ux/design-system/MASTER.md` in a given project root. Idempotent — same input writes byte-identical bytes. |
| `ux_persist_load` | Load `.ux/design-system/MASTER.md` back into a structured dict. |
| `ux_stats` | Return the engine version and per-manifest entry counts. Useful as a health probe. |
| `ux_image_extract` | Read a design image (PNG, JPG, WebP) and return a brief plus hints: dominant colors, canvas polarity, matched palette and style. Optionally runs the recommender on it. |
| `ux_synthesize` | Synthesize a design language from a brief: axes, palette, type pair, spacing, radius, motion. Offline and deterministic. |
| `ux_decisions_query` | Filter the local decisions ledger by industry, ui_type, command, minimum score or accepted only. |
| `ux_decisions_stats` | Aggregate stats over the local decisions ledger: totals, top brands, lint score median, acceptance rate. |
| `ux_system_build` | Build a WCAG-gated design system from a brand color, with a brief or seven axes optional; with `out`, write tokens.json, tokens.css, the font files and the report. |
| `ux_system_detect` | Find a design system a project already has and what it declares. Read it before any other tool; it is fixed input. |
| `ux_system_import` | Read an existing system (DTCG, CSS custom properties, Tailwind, markdown, Figma variables, or several files as one) in its own names. Returns counts, a proposed mapping and the import report. |
| `ux_system_enhance` | Measure an existing system and, with `scan`, the code that uses it. A report; nothing is rewritten. |
| `ux_system_extend` | Add foundations, roles or contracts without changing a token the system has: an extension file beside a system ux-skill did not write. |
| `ux_system_export` | Write a system as tokens.css, a Tailwind 4 theme, Figma variables or tokens.json, into `out` only. |
| `ux_contracts_check` | Check a folder of component contracts against a system, through its mapping. Returns counts and the problems folded by what they say. |
## Client configuration
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"ux-skill": {
"command": "ux-mcp",
"args": [],
"env": {}
}
}
}
```
If `ux-mcp` isn't on PATH, replace `"ux-mcp"` with the absolute path printed by `which ux-mcp`.
### Cursor
In `.cursor/mcp.json` at your project root (or globally at `~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"ux-skill": {
"command": "ux-mcp"
}
}
}
```
Then add a one-line hint to `.cursorrules`:
```
When designing UI, call the ux-skill MCP tools first: ux_recommend for the system, ux_lint to catch slop.
```
### Windsurf
In `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"ux-skill": {
"command": "ux-mcp"
}
}
}
```
### Generic stdio client
Any MCP client supporting stdio transport works. Spawn `ux-mcp` as a subprocess and exchange JSON-RPC frames on stdin/stdout. Logs land on stderr.
## Example tool calls
### `ux_recommend`
```json
{
"brief": {
"project_type": "landing",
"industry": "fintech-neobank",
"audience": ["founders", "operators"],
"tone": ["warm", "editorial", "precise"],
"must_have": ["dark-mode", "a11y-AA"],
"forbidden": ["brutalism", "purple-gradients"],
"stack": "nextjs-15-app-router",
"region": "mena"
}
}
```
Returns the full Recommendation: a picked style, palette, type pair, top 5 motion presets, top 12 compatible components, top 5 brand exemplars, all 35+ anti-pattern guardrails, and a rationale list explaining each pick.
### `ux_lint`
```json
{
"paths": ["./app", "./components"],
"threshold": "high"
}
```
Returns `{ findings, files_scanned, rules_loaded, exit_code, summary }`. `exit_code` is 1 if any finding meets or exceeds the threshold.
### `ux_palettes`
```json
{ "mode": "dark" }
```
Returns only dark-mode palettes.
### `ux_persist_save`
```json
{
"project_root": "/absolute/path/to/project",
"recommendation": { "...": "from ux_recommend" },
"brief": { "project_type": "landing" }
}
```
Writes `.ux/design-system/MASTER.md` and returns the absolute file path.
## How it works
The transport is **separated from the handlers**. Each tool is a pure `dict -> dict` Python function in `engine.mcp.server`, exercised by tests directly. `run_server()` is a thin async wrapper that wires those handlers into `mcp.server.stdio.stdio_server()`.
This means:
- The `engine.mcp` module imports cleanly **whether or not** the `mcp` Python package is installed.
- `ux-mcp` fails fast with a clear `pip install` hint if the transport library is missing.
- Tests run without the transport — no event loop, no subprocess plumbing.
## Why this is asymmetric
| Plugin | MCP server | Reach |
|---|---|---|
| **ux-skill** | yes (this) | any MCP host |
| ui-ux-pro-max-skill | no | Claude Code only |
| open-design | no | Claude Code only |
| taste-skill | no | Claude Code only |
| huashu-design | no | Claude Code only |
| stitch-skills | no | Claude Code only |
| nothing-design-skill | no | Claude Code only |
| hallmark | no | Claude Code only |
| material-3-skill | no | Claude Code only |
The competition is locked into Claude Code's plugin runtime. The MCP server makes ux-skill reachable from any agent — including agents that don't know what a "Claude Code plugin" is.
## Errors
- **`mcp package not installed`** → run `pip install 'uxskill[mcp]'` and try again.
- **`Unknown tool: foo`**: the tool name in the JSON-RPC call doesn't match one of the 25 in `TOOLS`. Check the table above.
- **`engine.mcp.server` import error** → likely pydantic missing from your environment; `pip install 'uxskill'` reinstalls the base deps.
© Laith Aljunaidy · MIT · Laith0003/ux-skill