Ballmac

io.github.vamsiy78v1.0.2更新于 Oct 7, 2026

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

已验证STDIO仅桌面Developer ToolsKnowledge & Memory

概览

AI 生成的概览

让助手搜索 React 与 Tailwind 组件目录、读取条目详情与源码，并获取 shadcn 安装命令或页面方案。

功能
Ballmac 提供 Ballmac UI 的 React 与 Tailwind 组件、区块和模板目录。工具包括 search_items、list_items、list_categories、get_item（描述、属性、键盘行为、依赖、完整源码）、get_examples、get_install_command（pnpm、npm、yarn 或 bun 的 shadcn CLI 命令）、compose_page（页面方案与 page.tsx 脚手架）和 get_setup。还提供目录资源和 build_page、choose_component 提示。
适用场景
当你使用 shadcn 风格组件构建或扩展 React 项目，并希望助手找到合适组件、读取其属性与源码，并给出准确的安装命令或基于区块的页面方案时，适合使用。
运行要求
通过 npx 以 stdio 在本地运行，需要 Node.js 20 或更高版本，无需全局安装。免费目录不需要账号或 API 密钥。可选环境变量：BALLMAC_UI_URL 用于指向其他目录，BALLMAC_LICENSE_KEY 用于读取 Pro 条目源码。
安装前请注意
该服务器被描述为只读：只返回信息和命令，不写入文件也不执行任何操作。若设置 BALLMAC_LICENSE_KEY，该许可密钥会发送到 Ballmac UI 网站，应视为机密。它返回的安装命令需要由你或助手执行，运行前请先检查。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Ballmac，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：packages/mcp/README.md，提交 e533082

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v1.0.2最新Oct 7, 2026