ui-mcp

MCP server that renders flexible, shadcn-styled UI in your local browser. Agents call render_ui to show dashboards, forms, charts, comparisons, and factual answers with numbers or spatial concepts — not just when building apps.

Quick start

npx ui-mcp init

This will:

1. Register the MCP server in .cursor/mcp.json (and .mcp.json for Claude Code)
2. Append agent instructions to AGENTS.md / CLAUDE.md so the model defaults to rendering (re-run init to refresh existing snippets)

Reload your editor MCP settings, then ask your agent to render something visual.

Tools

Tool	Description
render_ui	Create and open a UI view in the browser
update_ui	Update an existing view by id
list_ui_views	List active views and URLs
close_ui_view	Remove a view

Modes

• html — HTML fragment, wrapped in shadcn/Tailwind shell
• jsx — React component (App or Component), compiled in-browser via Babel
• page — Full HTML document (you control everything)

Style

The shell applies shadcn CSS variables and Tailwind semantic colors (bg-background, text-primary, etc.). The model is free to build any layout — no component whitelist.

Manual MCP config

{
  "mcpServers": {
    "ui-mcp": {
      "command": "npx",
      "args": ["-y", "ui-mcp"]
    }
  }
}

Environment

Variable	Default	Description
UI_MCP_PORT	3847	Preferred backend port

When should agents render?

There is no universal "after final answer" lifecycle hook across MCP clients. The reliable pattern is project instructions:

1. npx ui-mcp init — writes AGENTS.md / CLAUDE.md with a render-by-default policy
2. Cursor rules / project instructions — reinforce the behavior

Agents should call render_ui for most answers — especially numbers, measurements, comparisons, architecture, and workflows. Skip only for truly single-value replies (e.g. a port number) or when the user asks for text only. Re-run npx ui-mcp init to update an existing project's snippet in place.

Development

npm install
npm run build
node dist/bin/ui-mcp.js init

License

MIT