ballmac — Claude Code MCP server: what it does, how to install
Connects the Ballmac UI library to your coding agent to search React components, inspect props, and build page layouts. Works with shadcn CLI workflows.
claude mcp add ballmac -- npx -y @ballmac/mcpWhat ballmac does
This tool exposes Ballmac UI to MCP assistants. It lets the agent look up React and Tailwind elements by description, review prop signatures, and inspect keyboard interactions. Everything runs in read-only mode. The server delivers component details and terminal commands without modifying files on your machine.
Beyond component lookups, it includes helpers like compose_page to generate scaffold files and audit_project to catch styling flaws. Running it requires Node.js 20 or higher via npx. The free registry requires no credentials, while inspecting Pro assets needs a BALLMAC_LICENSE_KEY environment variable.
What it helps with
- search React and Tailwind components by feature description
- generate full page layouts with structured state scaffolding
- fetch exact shadcn installation commands for package managers
- audit existing files against UI and accessibility guidelines
Example prompts for the agent
- Design a SaaS pricing page with an FAQ section using Ballmac UI.
- Which Ballmac element should I use to display an animated counter?
- Plan a store dashboard layout and generate the page scaffold.
How to install ballmac
Platform CLI
claude mcp add ballmac -- npx -y @ballmac/mcpPlatform CLI
codex mcp add mcp -- npx -y @ballmac/mcpConfig file
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@ballmac/mcp"
]
}
}
}Config file
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ballmac/mcp"
]
}
}
}Platform CLI
gemini mcp add mcp npx -y @ballmac/mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ballmac
How do I install ballmac in Claude Code?
Run claude mcp add ballmac -- npx -y @ballmac/mcp in your terminal. You must have Node.js 20 or later installed on your system.
What does ballmac do?
It connects coding agents to the Ballmac UI catalog to search items, inspect code, and retrieve install commands. It operates in read-only mode and leaves all file modifications to the user or agent.
Does ballmac require an API key?
The standard registry is free and needs no authentication. A BALLMAC_LICENSE_KEY token is only required when fetching source code for items in the Pro tier.
