# ballmac

Connects the Ballmac UI library to your coding agent to search React components, inspect props, and build page layouts. Works with shadcn CLI workflows.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 11
- Author: vamsiy78
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/vamsiy78/ballmac-ui/tree/HEAD/packages/mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/ballmac

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add ballmac -- npx -y @ballmac/mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add mcp -- npx -y @ballmac/mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@ballmac/mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@ballmac/mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add mcp npx -y @ballmac/mcp
```

## When to use it
- 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
- 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.

## Similar
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74569
- [tldraw](https://affpapa.org/en/nevibecode/mcp/tldraw.md) — MCP server · ★ 51104
- [Figma-Context-MCP](https://affpapa.org/en/nevibecode/mcp/figma-context-mcp.md) — MCP server · ★ 16073
- [mcp-server-chart](https://affpapa.org/en/nevibecode/mcp/mcp-server-chart.md) — MCP server · ★ 4406
- [Dembrandt](https://affpapa.org/en/nevibecode/mcp/dembrandt.md) — MCP server · ★ 3851
- [RevoGrid DataGrid MCP Pro](https://affpapa.org/en/nevibecode/mcp/revogrid-datagrid-mcp-pro.md) — MCP server · ★ 3451

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md