@uxuiprinciples/mcp-server

MCP Server for UX/UI Principles — Agentic AI tools for Claude Code and Claude Desktop.

What is MCP?

Model Context Protocol (MCP) is an open protocol that enables AI assistants like Claude to interact with external tools and data sources. This server provides 12 tools for accessing 185 research-backed UX/UI principles.

Installation

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Restart Claude Desktop to activate.

Claude Code

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

Global Install

npm install -g @uxuiprinciples/mcp-server
uxui-mcp

Available Tools

Principle Tools

| Tool | Description | |------|-------------| | get_principle | Get a principle by slug with full content | | search_principles | Search by query, part, difficulty, or tags | | list_principles | List all principles or filter by part | | get_principle_prompts | Get vibe coding prompts for a principle |

Smell Tools (Anti-patterns)

| Tool | Description | |------|-------------| | get_smell | Get a smell with symptoms and fix recipe | | list_smells | List all smells, optionally by category | | detect_smell | Detect smells from a UI description | | suggest_fix | Get fix suggestions for a UX issue |

Flow Tools (User Journeys)

| Tool | Description | |------|-------------| | get_flow | Get a flow with pre/post-flight checklists | | list_flows | List all available flows | | generate_checklist | Generate checklist for a flow phase | | get_flow_principles | Get key principles for a flow |

Usage Examples

In Claude Desktop/Code

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
...

Agentic Workflow

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"]

Bilingual Support

All tools support English (en) and Spanish (es):

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

Data Included

• 185 principles across 6 parts
• 8 UX smells with fix recipes
• 5 user flows with checklists
• 2,098 academic citations
• Bilingual (English + Spanish)

Local Development

# Clone the repo
git clone https://github.com/joselhurtado/uxuiprinciples-web.git
cd uxuiprinciples-web

# Install dependencies
npm install

# Build packages
npm run build --workspace=@uxuiprinciples/principles-data
npm run build --workspace=@uxuiprinciples/mcp-server

# Run locally
node packages/mcp-server/dist/index.js

License

MIT © UX/UI Principles

Links

• uxuiprinciples.com - Full principles library
• MCP Documentation - Learn about MCP
• Claude Desktop - Download Claude Desktop