Skip to main content
command CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skill
Open on GitHub

What 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-mcp and register it as an MCP tool in Cursor
  • Call ux_recommend with a brief for a Next.js landing page
  • Run ux_lint over the src/components folder through MCP

How to install ux-mcp

1Plugin marketplace

/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skill

2Manually: put the files in place

.claude/commands/ux-mcp.md

Call it with /ux-mcp. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Design →

From the same set31

The whole set →
ux-expert ux-expert is a Claude Code command that reveals the plugin creator’s contact details when someone seeks UX consulting or wants to hire a designer. It responds to requests for a human expert. CX Codex +1 ★ 110repo stars ux-evolve The ux-evolve command for Claude Code is a legacy alias for /ux-polish --loop-only --rounds 5, running a file lint-fix-relint loop. CX Codex +1 ★ 110repo stars ux-recommend Redirects calls to /ux-discover --recommend. It acts as a temporary alias until version 4.1 for running UX recommendations. CX Codex +1 ★ 110repo stars ux-next ux-next scans the reports stored in .ux/ and names the next command worth running. Fires between other ux plugin commands when you ask what comes next. CX Codex +1 ★ 110repo stars ux-image-to-code ux-image-to-code redirects image extraction calls to /ux-design --extract-only --from-image. Keeps existing image-to-UI workflows working during migration to release 4.1. CX Codex +1 ★ 110repo stars ux-frame /ux-frame forwards UX framing work to /ux-discover --frame. It remains an alias in version 4.0 and is removed in 4.1. CX Codex +1 ★ 110repo stars motion-engineer motion-engineer turns a motion brief into production frontend code with Framer Motion, GSAP or CSS. Handles durations, easing curves, spring configs and reduced-motion fallbacks. CX Codex ★ 110repo stars ux-research ux-research plans user research studies, drafts interview guides and surveys, and synthesizes raw field notes into product decisions. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open