ballmac-ui-mcp
The Ballmac UI MCP server lets an AI agent discover, inspect, and install Ballmac UI components, blocks, and templates.
List or filter catalog items by kind, category, and tier (
free/pro).Browse category counts and names via
list_categories.Search the catalog with natural-language needs and synonyms.
Get full item details: description, usage guidance, props, keyboard behavior, dependencies, composition, template pages, and source.
Fetch working usage examples for an item.
Generate shadcn CLI install commands, including registry setup and Pro setup/by-URL options.
Compose a page from blocks for a given intent, with ordered sections, commands, scaffold, and matching templates.
Get project setup requirements and steps (shadcn init, registry entry, optional theme).
All tools are read-only and require no account; Pro source may need a license key.
Provides shadcn CLI setup and install commands for adding Ballmac UI components, blocks, and templates to a shadcn project; also supports catalog search, examples, props/source lookup, and page composition plans using Ballmac UI registry items.
Ballmac UI
Accessible React + Tailwind v4 components, blocks and templates in one design language. You add what you need with the shadcn CLI and the source lands in your project, ready to read and change. Your AI coding agent can search and install them too, through MCP. Now listed in the official shadcn registry directory.
Site and docs: ui.ballmac.com
What is in it
240+ components: primitives, forms, data display, navigation, feedback, motion, backgrounds, text effects, AI interfaces, developer tools, device frames and desktop-style surfaces.
60+ blocks and 17 templates: heroes, pricing, dashboards, sign-in, settings and more, composed from the components.
12 themes with a live builder, light and dark. Motion is part of the theme: speed, bounce, travel, hover and stagger, five ready-made feels, and a reduced-motion fallback. Data and form blocks show loading, empty, error, submitting and success through one
stateprop. Platform feels make every component handle like macOS, iOS or Windows, with window chrome for Tauri and Electron apps.Built to a standard: every item has examples, keyboard support, reduced-motion handling, right-to-left support and one translation provider for its built-in text. See
AUTHORING.md.Made for AI agents: each item carries a description, when to use it and when not to, what it composes with, and keyboard notes. Available through
llms.txt, a JSON API and the@ballmac/mcpserver.No collisions: everything installs into
components/ballmac/, so it never overwrites your shadcn/ui files.Verified installs: the release check installs every item into a fresh Next.js app, then type-checks and builds it.
Related MCP server: shadcn MCP Server
Quick start
You need a project with React 19, Tailwind CSS v4 and shadcn set up (npx shadcn@latest init; it creates components.json). Both the Base UI and
Radix styles work: components built on Radix UI also come in a Base UI version (guide).
# add components by name; npm dependencies are installed for you
npx shadcn@latest add @ballmac/button @ballmac/dockimport { Button } from "@/components/ballmac/button"@ballmac is in the official shadcn registry directory, so there is no registry to configure. On an older CLI, or to pin the address, run npx shadcn@latest registry add "@ballmac=https://ui.ballmac.com/r/{name}.json" once, or install by URL: npx shadcn@latest add https://ui.ballmac.com/r/button.json. Browse and preview everything at
ui.ballmac.com/components, and see the installation guide for
the optional Ballmac theme.
Use it with an AI agent
claude mcp add ballmac -- npx -y @ballmac/mcpOr install the skill, which teaches the agent the method (find, install, build to the rules, check) and reads your project first:
npx skills add vamsiy78/ballmac-uiThe server is read-only and needs no account. It searches the catalog, returns props, keyboard behaviour and source, gives the exact install
command, and can plan a whole page from blocks. Setup for Cursor, VS Code, Windsurf, Codex and Claude Desktop is in the
MCP docs and in packages/mcp. The official shadcn MCP server also works with this registry.
Free and Pro
Free (this repository) | Pro | |
Components, blocks, templates, themes | All of them, MIT licensed | Everything in Free |
Premium blocks | 150 more: heroes, features, pricing, dashboards, app screens, ecommerce, content and more | |
Starter apps | Beacon SaaS (teams, Stripe billing, dashboard), Quire (an AI assistant that cites its sources) and Cove (a Tauri desktop app that looks native on macOS and Windows) | |
Design tokens | Figma tokens for every theme | |
How you get it |
| A private registry ( |
Pro is commercial and licensed separately: its source is not in this repository. Details and pricing at ui.ballmac.com/pricing, setup at ui.ballmac.com/docs/guides/pro.
Repository
Path | What |
| Item source. Paths mirror install locations: |
| Item metadata: the single source of truth for the registry, site, search, |
| Examples, published as |
| The metadata schema |
| Theme presets and the colour engine behind the theme builder |
| The |
| The website, registry hosting ( |
| Registry build and quality checks |
| CI, the MCP release workflow, issue and pull request templates |
Develop
Needs Node.js 22 (what CI runs) and pnpm 10 (the repo pins it; corepack enable installs the right version, or use npx pnpm@10). The Pro registry is
optional: without it the site builds with the free items only.
pnpm install
pnpm build:registry # validate metadata, generate registry.json, run `shadcn build`, write site data
pnpm dev # website on http://localhost:3000Command | What it does |
| Dependency truth, licence provenance, RTL and translation checks, output schema validation |
| The usual |
| Install every item into a fresh Next.js app, then |
| axe on every |
A11Y_BASE_URL points the accessibility scan at a site that is already running.
Add an item
Write the source under
registry/ballmac/components/(importcnfrom@/lib/utils, other items from@/components/ballmac/...).Add
<name>.meta.tsnext to it withdefineItem({...}): description, category, dependencies, examples, notes for AI agents, andsourceif any code came from elsewhere.Add examples under
registry/examples/.Run
pnpm build:registry && pnpm check && pnpm smoke && pnpm a11y <name>.
AUTHORING.md is the full standard.
Contributing, support and security
Contributions are welcome: read
CONTRIBUTING.mdand the code of conduct.Bugs and requests: open an issue. Questions, or help with an item, a purchase or a licence key: ui.ballmac.com/support.
Security problems: report them privately as described in
SECURITY.md.Release notes:
CHANGELOG.mdand ui.ballmac.com/changelog.
License
Free components, blocks, templates and the MCP server are MIT licensed (see LICENSE). THIRD_PARTY_NOTICES.md
credits the open-source work they build on. Ballmac UI Pro is licensed separately.
Available Tools
8 toolscompose_pageCompose a page from blocksBRead-only
Plan a page from Ballmac UI blocks for an intent such as 'SaaS landing page with pricing and FAQ' or 'login screen'. Returns the chosen blocks in page order, install commands, a page.tsx scaffold that renders them, and any complete templates that already fit the intent.
Inputs: intent (required), includePro, packageManager. Returns: missing, commands, scaffold, sections, +1 more
get_examplesGet usage examplesBRead-only
Working example code for an item (the same examples shown on its page).
Inputs: name (required).
get_install_commandGet install commandsARead-only
The shadcn CLI commands to add one or more items to the user's project. Run setup once if components.json has no @ballmac registry, then add. byUrl works without setup for free items. Pro items install as @ballmac-pro/ and need proSetup once.
Inputs: names (required), packageManager. Returns: add, byUrl, setup, proSetup
get_itemGet a Ballmac UI itemARead-only
Everything about one item: description, when to use and not, import line, props, keyboard behaviour, dependencies, composition hints, template pages and the full source (for Pro items only when the server has BALLMAC_LICENSE_KEY; see the licence field). Set includeSource to false for a shorter answer.
Inputs: name (required), includeSource.
get_setupProject setupBRead-only
How to prepare a project for Ballmac UI (shadcn init, registry entry, optional theme) and its requirements.
Inputs: packageManager. Returns: steps, requirements, installLocation
list_categoriesList categoriesARead-only
How many components, blocks and templates there are, and the categories each is grouped into, with counts. Use the names as the category filter of list_items.
Inputs: no named parameters. Returns: blocks, totals, templates, components
list_itemsList Ballmac UI itemsARead-only
List components, blocks or templates, optionally filtered by kind, category (a component category such as primitives, motion or ai; a block section such as hero or pricing; or a template kind such as marketing) or tier. Call list_categories for the valid names.
Inputs: kind, tier, category. Returns: items
search_itemsSearch Ballmac UIARead-only
Search by what the user needs (for example 'chat input with attachments', 'animated stat', 'pricing section', 'online store'). Understands common synonyms such as modal, navbar or ecommerce. Returns the best matches with when-to-use guidance.
Inputs: query (required), kind, limit. Returns: items
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have clearly distinct purposes (list_items vs get_item vs compose_page). The only mild overlap is between list_items, list_categories, and search_items, plus get_item vs get_examples, but the descriptions clarify the boundaries (browse vs filter-by-category vs need-based search, full detail vs examples only).
All eight tools follow a consistent snake_case verb_noun pattern (get_examples, list_items, list_categories, search_items, get_item, get_install_command, compose_page, get_setup). No mixed conventions or vague verbs.
Eight tools is well-scoped for a UI component registry, covering discovery, detail, install and composition without bloat. Each tool earns its place.
The surface covers discovery (list/search/categories), inspection (get_item/get_examples), setup, install and page composition—a coherent read-only lifecycle for a component catalog. Minor gaps like versioning or license-status checks exist but are workable.
Maintenance
Related MCP Connectors
Search free React, Tailwind, and shadcn components, blocks, and dashboards; get installable source.
React components and blocks with motion. Search docs, props and shadcn install commands.
React + Tailwind UI components and recipes your AI coding tool can search and install.
React + Tailwind UI components and recipes your AI coding tool can search and install.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to discover, install, and generate code examples for shadcn/ui components, providing installation commands and usage examples for 37+ React UI components.MIT
- FlicenseAqualityDmaintenanceProvides AI assistants with direct access to shadcn/ui components and blocks, enabling real-time fetching of component source code, documentation, and implementation examples.422 npm4-
- AlicenseAqualityDmaintenanceProvides coding agents live access to shadcn-style component registries, enabling them to search, compare, and fetch real component source code for UI composition.572 npm6MIT
- AlicenseAqualityDmaintenanceProvides AI assistants with comprehensive access to shadcn/ui v4 components, blocks, demos, and metadata across React, Svelte, Vue, and React Native, enabling efficient component integration and code generation.106,787 npmMIT