Uxui Principles

@uxuiprinciples/mcp-server

MCP server for UX/UI Principles: 195 research-backed principles with their citations, 12 UX smells with fix recipes and 12 user-flow checklists, in English and Spanish, inside Claude Code, Claude Desktop, Cursor, VS Code, Windsurf or any MCP client.

Free and offline by default: the dataset ships inside the package and the server makes no network call. A Principles Library API key turns on pro mode, which adds the full guide bodies, the AI prompts and an interface audit through the uxuiprinciples.com API.

What is MCP?

Model Context Protocol (MCP) is an open protocol that lets an AI assistant call external tools. This server speaks MCP over stdio and registers 13 tools.

Installation

Requires Node.js 18 or newer. npx -y fetches the latest version on first run.

Claude Code

claude mcp add uxui-principles -- npx -y @uxuiprinciples/mcp-server

Add --scope user to make it available in every project. Confirm with claude mcp list.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop:

{

"mcpServers": { "uxui-principles": { "command": "npx", "args": ["-y", "@uxuiprinciples/mcp-server"] } } }

Cursor

Add to .cursor/mcp.json in the project (or ~/.cursor/mcp.json for every project), then enable the server in Cursor Settings, MCP:

{

"mcpServers": { "uxui-principles": { "command": "npx", "args": ["-y", "@uxuiprinciples/mcp-server"] } } }

VS Code

Add to .vscode/mcp.json in the workspace, then start the server from the MCP panel or let Copilot agent mode start it:

{

"servers": { "uxui-principles": { "type": "stdio", "command": "npx", "args": ["-y", "@uxuiprinciples/mcp-server"] } } }

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json, then refresh the MCP list in Cascade:

{

"mcpServers": { "uxui-principles": { "command": "npx", "args": ["-y", "@uxuiprinciples/mcp-server"] } } }

Global install

npm install -g @uxuiprinciples/mcp-server

uxui-mcp

Point the client at the uxui-mcp binary instead of npx. Re-run the install to pick up new versions.

Pro mode (Principles Library key)

The Principles Library ($59/year) includes a REST API key. Give it to the server as the UXUI_API_KEY environment variable and four tools change:

Everything else keeps running offline. If the API is unreachable, get_principle and get_principle_prompts fall back to the free answer and report the failure in proError; audit_interface and check_requirements return the error code.

{

"mcpServers": { "uxui-principles": { "command": "npx", "args": ["-y", "@uxuiprinciples/mcp-server"], "env": { "UXUI_API_KEY": "uxui_live_..." } } } }

For Claude Code: claude mcp add uxui-principles -e UXUI_API_KEY=uxui_live_... -- npx -y @uxuiprinciples/mcp-server. The key is read from the environment only and is never logged. Get or rotate yours at uxuiprinciples.com/account. The server's startup line on stderr says pro mode or free mode, and the instructions it hands the client say the same.

Available tools

Principles

Smells (anti-patterns)

Flows (user journeys)

Pro

Usage examples

You: What principle should I follow for form design?

Claude: Let me search for form-related principles... [Calls search_principles with query="form"]

Based on the UX/UI Principles database, here are the key principles for form design:

1. Progressive Disclosure (D.1.1.01) - Show only essential fields initially
2. Inline Validation - Validate as users type
3. Smart Defaults - Pre-fill common choices

...

You: My login form has a 60% abandonment rate. Help me fix it.

Claude: Let me detect potential UX issues... [Calls detect_smell with description="login form high abandonment"]

I detected "Form Graveyard" smell with high confidence. Let me get the fix recipe... [Calls get_smell with id="form-graveyard"]

Here's my analysis and recommendations:

1. Reduce fields to email + password only
2. Add social login options
3. Use inline validation

...

Let me also get the flow checklist for the form... [Calls generate_checklist with flow_id="forms" phase="postflight"]

With a key:

You: Audit this checkout: three steps, no order summary until the last one, the Pay button is disabled with no explanation until every field validates.

Claude: [Calls audit_interface with the description] Score 58, fair. Two warnings: Visibility of System Status (order summary hidden) and Silent Errors (disabled button without feedback). Priority fix: ...

After building a screen:

You: Build the settings page: profile form, an AI summary of recent activity, and a danger zone with "Delete account". Then check it.

Claude: [Builds the page, then calls check_requirements with flow "settings", the components, the actions (Delete account flagged consequential) and the states it implemented] 3 of 6 applicable rules fail: undo-or-edit (User Control and Freedom, Nielsen 1994), show-sources (AI Source Citations, Liu et al. 2023), ai-error-recovery (Efficient AI Correction, Amershi et al. 2019). Adding an undo toast, a sources line under the summary and a regenerate control...

Bilingual support

All tools accept locale: "en" | "es". detect_smell and suggest_fix understand descriptions written in either language whatever the locale:

search_principles({ query: "navegación", locale: "es" })

detect_smell({ description: "el formulario es demasiado largo", locale: "es" })

Data included

• 195 principles across 6 parts, with 500+ bibliographic references returned by get_principle (the guides cite 2,400+ academic citations in full)
• 12 UX smells with fix recipes
• 12 user flows with checklists
• Bilingual (English + Spanish)

Local development

git clone https://github.com/joselhurtado/uxuiprinciples-web.git

cd uxuiprinciples-web npm install npm run build --workspace=@uxuiprinciples/principles-data npm run build --workspace=@uxuiprinciples/mcp-server node packages/mcp-server/dist/index.js

npm run smoke-test --workspace=@uxuiprinciples/mcp-server packs the build, installs it in a temp project and drives both modes over stdio (pro mode against a local fake of the API). server.json next to this README is the MCP Registry manifest; publish with mcp-publisher publish after the npm release.

License

MIT © UX/UI Principles

Links

• uxuiprinciples.com - Full principles library
• MCP documentation on the site
• REST API - The same data over HTTPS
• MCP Documentation - Learn about MCP