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