Skip to main content
Glama

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

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

npm 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 tools
audit_interfaceAudit an interfaceA
Read-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 rulesA
Read-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 descriptionA
Read-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 checklistA
Read-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 flowA
Read-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 flowA
Read-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 principleA
Read-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 principleA
Read-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 smellA
Read-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 flowsA
Read-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 principlesA
Read-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 smellsA
Read-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 principlesA
Read-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 issueA
Read-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

    A4.2/5.0

    Scored across 14 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      29
      69 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An 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.
      6
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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 npm
      MIT