@properui/mcp is a Model Context Protocol server, local over stdio and remote at properui.dev/api/mcp, that gives Claude Code, Cursor, Codex, Windsurf and VS Code the Proper UI registry as tools.
@properui/mcp is a Model Context Protocol server. It gives an MCP-aware assistant the Proper UI registry and the CLI's add as tools, so it can search for a component by description, read its real source and docs, and install it with its dependency chain without leaving the chat or shelling out to npx @properui/cli for every lookup.
It also runs as a remote endpoint, https://properui.dev/api/mcp (Streamable HTTP, stateless, no account), which needs nothing installed. The product overview is on the MCP page.
It is not a second implementation: the registry client, fuzzy search, add, info and check are the CLI's own modules, bundled into the server. A file add_component writes is exactly what properui add would have written.
Connect it
Two ways, and one difference. The remote endpoint has no access to your project, so it searches, inspects and plans, and the agent installs with the CLI using the command from get_install_plan. The stdio server runs in your project, so add_component installs directly. It runs through npx, so there is nothing to install first.
Remote (Claude Code, Codex, Gemini CLI, Cursor, and Claude and ChatGPT as custom connectors):
claude mcp add --transport http properui https://properui.dev/api/mcp
codex mcp add properui --url https://properui.dev/api/mcp
gemini mcp add --transport http properui https://properui.dev/api/mcp
Cursor takes { "mcpServers": { "properui": { "url": "https://properui.dev/api/mcp" } } } in .cursor/mcp.json. Per-client steps, including Claude Desktop and ChatGPT, are in the MCP reference.
Local (stdio), Claude Code:
claude mcp add properui -- npx -y @properui/mcp
Local (stdio), Cursor (.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and Claude Desktop:
{
"mcpServers": {
"properui": {
"command": "npx",
"args": ["-y", "@properui/mcp"]
}
}
}
Codex (~/.codex/config.toml):
[mcp_servers.properui]
command = "npx"
args = ["-y", "@properui/mcp"]
VS Code (.vscode/mcp.json):
{
"servers": {
"properui": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@properui/mcp"]
}
}
}
npx @properui/cli@latest agent init writes the Claude Code (.mcp.json) and Cursor (.cursor/mcp.json) entries for you, next to the Proper UI Skill, and prints the Codex block. See AI agents & the Proper UI Skill.
Tools
| Tool | What it does |
|---|---|
list_components | Registry entries (name, layer, type, title, description), filtered by layer, type and platform |
search_components | Fuzzy search over names, titles, descriptions, example names and exported symbols, scored like properui search |
search_screens | Fuzzy search over full-page examples: dashboards, settings, auth, onboarding, billing, 404s, email templates |
search_sections | Fuzzy search over marketing section variants: heroes, pricing, features, testimonials, footers |
search_flows | Curated ordered sequences of screens, each step with its purpose |
compare_screens | Two to five entries side by side: shared components and tokens, and what is unique to each |
get_component | One entry in full: every file with its source, npm and registry dependencies, usage guidance and the docs URL |
get_component_docs | The entry's docs page as markdown |
get_install_plan | What installing entries would do: registry dependencies, npm packages, files, and the exact CLI command. Writes nothing |
add_component | properui add: resolves registryDependencies, rewrites @/ imports, records the install, returns the npm install command |
get_project_info | properui info --json: framework, Tailwind, aliases, theme path, registry reachability, installed entries |
check_tokens | properui check: raw palette classes, dark: variants and arbitrary colour values in a file or directory |
Over HTTP the server offers every tool except the last three (add_component, get_project_info, check_tokens), which need a project on disk. The server also has a build_screen prompt and a properui://stats resource, and the registry index and every entry are resources over both transports (properui://registry/index, properui://registry/<name>). Parameters and sample results for each tool are in the MCP reference.
Search results carry thumbnails, which are images served by this docs site (https://properui.dev/thumbs/...). add_component needs components.json, so run npx @properui/cli@latest init first; there is no init tool. It never runs the package manager unless the call passes install: true: by default it returns the install command for the agent to run or show you.
Another registry
The server resolves the registry the way the CLI does: --registry <source> after the package name, then PROPERUI_REGISTRY, REGISTRY_URL, the registry field of the project's components.json, then https://properui.dev/r. A directory on disk works too, e.g. "args": ["-y", "@properui/mcp", "--registry", "./packages/registry/dist"].