Ballmac

io.github.vamsiy78v1.0.2Updated Oct 7, 2026

Search, inspect and install Ballmac UI React and Tailwind components, blocks and templates.

VerifiedSTDIODesktop onlyDeveloper ToolsKnowledge & Memory

Overview

AI-generated overview

Lets an assistant search a React and Tailwind component catalog, read item details and source, and get shadcn install commands or page plans.

What it does
Ballmac exposes the Ballmac UI catalog of React and Tailwind components, blocks and templates. Tools include search_items, list_items, list_categories, get_item (description, props, keyboard behaviour, dependencies, full source), get_examples, get_install_command (shadcn CLI commands for pnpm, npm, yarn or bun), compose_page (page plan plus page.tsx scaffold) and get_setup. It also offers catalog resources and build_page and choose_component prompts.
When to use it
Use it when building or extending a React project with shadcn-style components and you want the assistant to find the right component, read its props and source, and produce the exact install command or a page plan from blocks.
Requirements
Runs locally over stdio via npx, so Node.js 20 or later is required; no global install. No account or API key is needed for the free catalog. Optional environment variables: BALLMAC_UI_URL to point at a different catalog, and BALLMAC_LICENSE_KEY for Pro item source.
Before you install
The server is described as read-only: it returns information and commands and does not write files or run anything. If you set BALLMAC_LICENSE_KEY, that licence key is sent to the Ballmac UI site; treat it as a secret. Install commands it returns are meant to be run by you or your assistant, so review them before executing.

Installation

In SourceWeft

  1. Open Ballmac in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@ballmac/mcp

An MCP server for Ballmac UI. It lets Claude, Cursor, VS Code, Windsurf, Codex and any other MCP client search the catalog of components, blocks and templates, read an item's props, keyboard behaviour and source, get the exact install command, and plan whole pages from blocks.

It is read-only: it answers questions and returns commands, and never writes files or runs anything on your machine. No account or API key is needed for the free catalog.

Install

The server runs with npx, so there is nothing to install globally. Node.js 20 or later is required.

Claude Code

bash
claude mcp add ballmac -- npx -y @ballmac/mcp

Claude Desktop

Add this to claude_desktop_config.json (Settings, Developer, Edit config):

json
{  "mcpServers": {    "ballmac": {      "command": "npx",      "args": ["-y", "@ballmac/mcp"]    }  }}

Cursor

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:

json
{  "mcpServers": {    "ballmac": {      "command": "npx",      "args": ["-y", "@ballmac/mcp"]    }  }}

VS Code

Add this to .vscode/mcp.json:

json
{  "servers": {    "ballmac": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@ballmac/mcp"]    }  }}

Windsurf

Add the same mcpServers block as Cursor to ~/.codeium/windsurf/mcp_config.json.

Codex

Add this to ~/.codex/config.toml:

toml
[mcp_servers.ballmac]command = "npx"args = ["-y", "@ballmac/mcp"]

What it can do

ToolWhat it returns
search_itemsThe best matches for a need, such as "chat input with attachments" or "online store". Understands common synonyms (modal, navbar, ecommerce).
list_itemsComponents, blocks or templates, filtered by kind, category or tier.
list_categoriesTotals and every category with its count, so the agent knows what exists.
get_itemDescription, when to use and when not to, import line, props, keyboard behaviour, dependencies, template pages and the full source.
get_examplesThe working examples shown on the item's page.
get_install_commandThe shadcn CLI commands for pnpm, npm, yarn or bun.
compose_pageA page plan from blocks in the right order, install commands, a page.tsx scaffold, and any complete template that already fits.
get_setupHow to prepare a project (shadcn init, registry entry, optional theme).

Resources: ballmac://catalog (every item with a one-line description) and ballmac://items/{name} (one item as Markdown).

Prompts: build_page (plan and build a page from an intent) and choose_component (find and wire up the right component).

Tools that return lists also return structured content, so clients that support it get typed results.

Things to ask

  • "Build a SaaS landing page with pricing and an FAQ using Ballmac UI."
  • "Which Ballmac component should I use for an animated revenue number?"
  • "Add a login screen from Ballmac UI to this app."
  • "Is there a Ballmac template for an online store? Install it."

Options

VariableDefaultPurpose
BALLMAC_UI_URLhttps://ui.ballmac.comThe catalog to read, for example a local copy of the site.
BALLMAC_LICENSE_KEYnoneA Ballmac UI Pro licence key. With it, get_item and get_examples return the source of Pro items too.

Pro items

Pro items appear in search with tier: "pro". Their install commands use the @ballmac-pro namespace, and get_install_command returns a proSetup line with the components.json entry the shadcn CLI needs. To let the agent read Pro source, pass your key to the server:

bash
claude mcp add ballmac --env BALLMAC_LICENSE_KEY=your-licence-key -- npx -y @ballmac/mcp

In JSON configs, add "env": { "BALLMAC_LICENSE_KEY": "your-licence-key" } next to args. The key is only sent to the Ballmac UI site. Setup guide: ui.ballmac.com/docs/pro.

npx @ballmac/mcp --help and --version work from a terminal.

Without MCP

Ballmac UI is also a standard shadcn registry, so the official shadcn MCP server can browse it once the registry is in your components.json:

bash
npx shadcn@latest registry add @ballmac=https://ui.ballmac.com/r/{name}.json

License

MIT

Source: packages/mcp/README.md at commit e533082

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v1.0.2LatestOct 7, 2026