uxui-principles
UX/UI Principles MCP server
Source of @uxuiprinciples/mcp-server: 195 research-backed UX/UI principles with their citations, 12 UX smells with fix recipes and 12 user-flow checklists, in English and Spanish, for Claude Code, Claude Desktop, Cursor, VS Code, Windsurf or any MCP client.
Install, tools, pro mode and troubleshooting: packages/mcp-server/README.md or uxuiprinciples.com/en/docs/mcp.
claude mcp add uxui-principles -- npx -y @uxuiprinciples/mcp-serverAbout this repository
This is a read-only mirror. The code is developed in a private monorepo and pushed here by a workflow on every change to the packages and on every release tag (which also cuts a GitHub release here), so pull requests cannot be merged; issues are welcome and get answered. The dataset in packages/principles-data/src/generated/dataset.ts is the same public catalogue (metadata, summaries, citations) that ships in the npm package; the full guides and the AI prompts stay in the Principles Library.
Related MCP server: VitalyGPT MCP
Run from source
npm install
npm run build
node packages/mcp-server/dist/index.jsnpm run smoke-test packs the server, installs it in a temp project and drives both modes over stdio. The Dockerfile builds the same server for registry checks.
MIT, UX/UI Principles.
Available Tools
14 toolsaudit_interfaceAudit an interfaceARead-onlyIdempotent
Audit a described screen or flow: returns findings mapped to principles and UX smells, each with severity, remediation and business impact, plus a score, the detected interface type, strengths and the three priority fixes. Pro mode only (UXUI_API_KEY set): the audit runs on the uxuiprinciples.com API. Without a key use detect_smell then suggest_fix, which run offline.
Inputs: description (required), depth, locale, context.
check_requirementsCheck a screen against the required-state rulesARead-onlyIdempotent
Check a screen you built or designed against eight experience requirements: confirmation before consequential actions, error state, empty state, loading state, undo or edit, sources on AI output, recovery after an AI error, consent before automation. Describe the screen as data (flow, components, actions with flags, states implemented) and get pass, fail or not_applicable per rule, each with the principle it comes from and its citations, plus a markdown summary. Call it after generating or changing a screen and fix every fail. Pro mode only (UXUI_API_KEY set); without a key use generate_checklist for the unevaluated checklist.
Inputs: flow, locale, actions, components, +1 more.
detect_smellDetect UX smells from a descriptionARead-onlyIdempotent
Detect which UX smells match a plain-language description of an interface problem or a user complaint, in English or Spanish. Returns the matched smells with a confidence level and the suggested fix for each. Use it as the first step when a UI "feels off" and the cause is not named yet; runs offline.
Inputs: description (required), locale.
generate_checklistGenerate a flow checklistARead-onlyIdempotent
Generate the pre-flight (before design) or post-flight (before ship) checklist for one user flow. Returns the checklist as structured items (each tied to a principle) and as ready-to-paste markdown. Use it to review a design or a pull request against the flow it implements.
Inputs: phase (required), flow_id (required), locale.
get_flowGet a user flowARead-onlyIdempotent
Get one user flow (onboarding, forms, pricing, dashboard, checkout, search, authentication and more) with its target metrics, the pre-flight checklist to run before designing it and the post-flight checklist to run before shipping it. Use it before designing or shipping a known flow.
Inputs: id (required), locale.
get_flow_principlesGet the principles behind a flowARead-onlyIdempotent
Get the key principles that govern one user flow and the UX smells that most often break it. Returns the principle slugs and the smell ids so you can read them with get_principle and get_smell. Use it to ground a flow review in evidence.
Inputs: flow_id (required), locale.
get_principleGet a principleARead-onlyIdempotent
Get one UX/UI principle by slug: title, code, part, difficulty, summary, the bibliographic citations behind it (author, title, year, url) and the link to the full guide on uxuiprinciples.com. With UXUI_API_KEY set (pro mode) the full guide body comes back in content. Use it to identify, summarize or cite a specific principle; use search_principles first when you only have a topic.
Inputs: slug (required), locale.
get_principle_promptsGet the AI prompts of a principleARead-onlyIdempotent
Get the ready-to-use AI prompts attached to one principle (prompts to apply, audit or refactor an interface against it). With UXUI_API_KEY set (pro mode) the prompt texts come back in prompts; without it the prompts belong to the paid Principles Library and the tool returns the count and the URL of the guide. Call get_principle first if you only need the summary.
Inputs: slug (required), locale.
get_smellGet a UX smellARead-onlyIdempotent
Get one UX smell (interface anti-pattern) by id: name, tagline, symptoms, the Nielsen heuristic it breaks, a step-by-step fix recipe with a time estimate, the related principles and an audit prompt plus a refactoring prompt. Use it once you know the smell id, from list_smells or detect_smell.
Inputs: id (required), locale.
list_flowsList user flowsARead-onlyIdempotent
List the 12 user flows covered by the checklists (onboarding, forms, pricing, dashboard, empty states, checkout, settings, navigation, search, authentication, notifications, data tables) with the target metric of each. Returns id, name, description, metric target and the number of checklist items per phase. Use it to pick the id for get_flow, generate_checklist or get_flow_principles.
Inputs: locale.
list_principlesList principlesARead-onlyIdempotent
List the 195 UX/UI principles, optionally one part at a time. Returns principle summaries (slug, title, code, part name, summary), the total count and the list of part ids. Use it to browse the catalogue or to learn the part ids for search_principles.
Inputs: part, limit, locale.
list_smellsList UX smellsARead-onlyIdempotent
List the 12 UX smells (interface anti-patterns such as overloaded screens, form graveyards, silent errors or the AI-aesthetic cliches), optionally filtered by category. Returns id, name, short name, tagline, category and Nielsen heuristic for each. Use it to browse the catalogue before get_smell.
Inputs: locale, category.
search_principlesSearch principlesARead-onlyIdempotent
Search the 195 UX/UI principles by free text, part, difficulty or tags. Returns the matching principles with slug, title, code, part name and summary, plus the total count. Use it to find which principles apply to a design question before calling get_principle.
Inputs: part, tags, limit, query, +2 more.
suggest_fixSuggest a fix for a UX issueARead-onlyIdempotent
Get a fix for a described UX issue: detects the most likely smell (or uses the one you pass), then returns its step-by-step fix recipe, the principles to apply and a refactoring prompt you can hand to a coding agent. Use it when you want an actionable remedy rather than a diagnosis; runs offline.
Inputs: issue (required), locale, smell_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
The catalogue tools are cleanly tiered (list → search → get) across three distinct resources (principles, smells, flows), so picking one is easy. Two overlaps remain: audit_interface vs check_requirements both evaluate a described screen, and get_flow already returns pre/post-flight checklists that generate_checklist also produces, so an agent must read descriptions to choose.
Every tool is snake_case with a leading verb (get_, list_, search_, detect_, suggest_, generate_, audit_, check_), and the pattern maps predictably onto resource nouns. Companion tools share stems (list_principles/get_principle, list_smells/get_smell, list_flows/get_flow), which makes the surface easy to scan.
14 tools sits comfortably in the well-scoped range and each one maps to a real step: browse/search/read for principles, smells and flows, plus audit and checklist generation. Nothing feels padded, and the pro/offline notes are consistent across the set.
The read-only reference domain is well covered: principles (list/search/get/prompts), smells (list/get/detect/fix), flows (list/get/checklist/principles) plus audit and requirement checks. Minor gaps: no free-text smell search outside detect_smell, no way to fetch several principles in one call, and no direct path from an audit finding back to its principle other than a second call.
Maintenance
Related MCP Connectors
Remote MCP server that gives Claude, ChatGPT, Cursor or any MCP client Google search volume, CPC, competition and similar keywords for 50+ countries. Works with no signup at 20 lookups a day; sign in with OAuth or an API key for higher limits, or $4.99 a month for unlimited.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for VertaaUX.ai — run UX & accessibility audits, generate fixes, and monitor quality from your LLM or IDE. 38 tools covering the full audit-to-fix lifecycle across 7 UX categories.2969 npmMIT
- AlicenseAqualityCmaintenanceMCP server providing UX insights from Vitaly Friedman as searchable tools for any LLM.415 npm4MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that works with Mobbin — 600k+ real app screens and flows from 1,100+ apps. Search screens, browse flows, grab palettes, build better UI without leaving Claude.6ISC
- AlicenseNot gradedqualityDmaintenanceMCP server for design decisions during a build, providing live UI/animation library docs (via llms.txt) and a curated knowledge base of UX laws and UI conventions. It enables agents to look up real component APIs and apply design best practices, running locally via stdio or hosted on Vercel.6 npmMIT