ballmac

@ballmac/mcp

Ballmac UI 用の MCP サーバーです。Claude、Cursor、VS Code、Windsurf、Codex など、あらゆる MCP クライアントから、コンポーネント、ブロック、テンプレートのカタログを検索したり、各項目の props、キーボード操作、ソースを確認したり、正確なインストールコマンドを取得したり、ブロックからページ全体を計画したりできます。

読み取り専用です。質問に回答してコマンドを返すだけで、お使いのマシン上のファイルを書き換えたり、何かを実行したりすることはありません。無料カタログの利用にアカウントや API キーは必要ありません。

インストール

サーバーは npx で実行するため、グローバルにインストールする必要はありません。Node.js 20 以降が必要です。

Claude Code

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

Claude Desktop

claude_desktop_config.json に追加します（Settings、Developer、Edit config）。

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

Cursor

プロジェクトの .cursor/mcp.json、またはすべてのプロジェクトで使う場合は ~/.cursor/mcp.json に追加します。

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

VS Code

.vscode/mcp.json に追加します。

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

Windsurf

Cursor と同じ mcpServers ブロックを ~/.codeium/windsurf/mcp_config.json に追加します。

Codex

~/.codex/config.toml に追加します。

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

できること

ツール	返される内容
search_items	「添付ファイルに対応したチャット入力」や「オンラインストア」など、ニーズに最も合った項目を返します。よく使われる同義語（modal、navbar、ecommerce）も理解します。
list_items	種類、カテゴリ、またはティアで絞り込んだコンポーネント、ブロック、テンプレートを返します。
list_categories	合計数と、各カテゴリおよびその件数を返すため、エージェントは利用可能な項目を把握できます。
get_item	説明、使用する場合と使用しない場合、import 文、props、キーボード操作、依存関係、テンプレートページ、完全なソースを返します。
get_examples	項目のページに掲載されている、動作するサンプルを返します。
get_changes	項目のバージョンごとの変更内容（since を指定すると、それ以降の変更のみを表示）と、破壊的変更の有無を返します。
get_quality_rules	Ballmac アプリに適用されるルール（状態、アクセシビリティ、トークン、モーション、レイアウト）と、その理由、および良い例と悪い例を返します。コンポーネントを書く前に確認してください。
audit_project	プロジェクトのソースを読み取り専用で監査します。重大度の高い順に、修正方法とともに指摘事項を返します。タスクの完了を報告する前に実行してください。
make_preset	説明からデザインシステム全体（色、角丸、書体、プラットフォームの雰囲気、モーション）を作成し、16 文字のコードとインストールコマンドを返します。
get_tests	項目に付属する vitest + Testing Library のテストを返します。編集後も正常に動作することを確認できます。
get_install_command	pnpm、npm、yarn、または bun 用の shadcn CLI コマンドを返します。
compose_page	適切な順序で並べたブロックからのページ計画、インストールコマンド、page.tsx のひな形、および要件に合う完全なテンプレートがあればそれを返します。各セクションには、そのブロックが表示できる状態が記載されます。また、ひな形ではデータブロックを useResource に、フォームブロックを制御用の状態に接続します。リクエストで macOS、Windows、iOS、Tauri、Electron が指定された場合（または feel を渡した場合）は、インストールするプラットフォームの雰囲気と接続に関するメモも返します。
get_setup	プロジェクトの準備方法（shadcn init、任意のテーマ、古い CLI で必要となるレジストリエントリー）を返します。

リソース：ballmac://catalog（すべての項目と一行の説明）および ballmac://items/{name}（Markdown 形式の項目 1 つ）。

プロンプト：build_page（意図に基づいてページを計画し、構築する）および choose_component（適切なコンポーネントを見つけて接続する）。

リストを返すツールは構造化コンテンツも返すため、対応しているクライアントでは型付きの結果を取得できます。

質問例

• 「Ballmac UI を使って、料金プランと FAQ を含む SaaS のランディングページを作成して。」
• 「アニメーション付きの売上金額表示には、Ballmac のどのコンポーネントを使えばよいですか？」
• 「このアプリに Ballmac UI のログイン画面を追加して。」
• 「オンラインストア向けの Ballmac テンプレートはありますか？あればインストールして。」

オプション

変数	デフォルト	用途
BALLMAC_UI_URL	https://ui.ballmac.com	読み込むカタログです。たとえば、サイトのローカルコピーを指定できます。
BALLMAC_LICENSE_KEY	なし	Ballmac UI Pro のライセンスキーです。このキーを指定すると、get_item と get_examples は Pro アイテムのソースも返します。

Pro アイテム

Pro アイテムは、tier: "pro" を指定した検索結果に表示されます。インストールコマンドでは @ballmac-pro 名前空間が使われ、get_install_command は、shadcn CLI が必要とする components.json の項目を含む proSetup 行を返します。エージェントが Pro のソースを読み込めるようにするには、サーバーにキーを渡します。

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

JSON 設定では、args の隣に "env": { "BALLMAC_LICENSE_KEY": "your-licence-key" } を追加します。キーは Ballmac UI サイトにのみ送信されます。セットアップガイド：ui.ballmac.com/docs/pro。

npx @ballmac/mcp --help と --version はターミナルから実行できます。

MCP を使わない場合

Ballmac UI は標準的な shadcn レジストリでもあるため、公式の shadcn MCP サーバーから参照できます。shadcn CLI は公式レジストリディレクトリから @ballmac を認識しますが、その MCP サーバーは components.json に記載されたレジストリのみを読み込むため、そこに追加してください。

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

ライセンス

MIT