# shadcndashboard-mcp

Official Model Context Protocol (MCP) server for [Shadcn Dashboard](https://shadcndashboard.dev).

This MCP server allows AI-powered IDEs and agents to discover, search, and install **Shadcn Dashboard** UI blocks directly into your projects — with in-memory caching, token-efficient lightweight listings, upfront Free vs PRO discovery, layout composition blueprints, and automatic JSX code snippets.

## Install MCP configuration

```bash
npx shadcndashboard-cli install <client>
```

### Supported Clients

- [x] cursor
- [x] windsurf
- [x] claude
- [x] cline
- [x] antigravity

## Manual Installation

Add to your IDE's MCP config:

```json
{
  "mcpServers": {
    "shadcndashboard-mcp": {
      "command": "npx",
      "args": ["-y", "shadcndashboard-mcp@latest"]
    }
  }
}
```

For MCP, visit its [**MAIN PAGE**](https://shadcndashboard.dev/mcp)  
For more information visit our documentation on [**How to use MCP Server**](https://shadcndashboard.dev/docs/getting-started/mcp-server-docs)

---

## Available Tools

The server provides the following tools callable via MCP:

| Tool Name                      | Description                                                                                                                                                     |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_audit_checklist`          | **Run first.** Returns strict workflow rules, `components.json` pre-requisites, Free vs PRO rules, and shell layout requirements.                               |
| `listBlocks`                   | Lists all Shadcn Dashboard blocks with category (`shells`, `charts`, `metrics`, `tables`, `forms`, `layout`, `ai-ops`) and license tier (`free`, `pro`, `all`) filtering. |
| `listFreeBlocks`               | Dedicated shortcut tool to list only 100% free blocks that require no license.                                                                                  |
| `listComponents`               | Provides a lightweight list of Shadcn Dashboard UI components with optional tier filtering.                                                                     |
| `getBlockInstall`              | Returns the official installation command, component export name, import statement, and clean JSX usage snippet.                                                |
| `searchBlocks`                 | Search blocks by keywords or tags with optional license tier filtering (`free`, `pro`, `all`).                                                                  |
| `listInstalledBlocks`          | Lists all blocks that are currently installed in the project.                                                                                                   |
| `getDashboardLayoutGuidelines` | Get dashboard shell priority rules, domain composition recipes (AI Ops, SaaS, Ecommerce, Logistics, Healthcare), and CSS Grid / Flex alignment & height-balancing guidelines. |
| `handleError`                  | Intelligent error classifier and recovery guide for missing `components.json`, license, CLI, or not-found errors.                                               |

---

## Available Prompts

The server provides rich prompts to guide AI agents through common workflows:

| Prompt/Command             | Description                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| `search`                   | Search for components or blocks by topic.                                                       |
| `create-ui`                | Architect a full UI page using prebuilt dashboard shells and balanced grid layouts.             |
| `build-dashboard`          | Build a complete domain-specific dashboard (AI Ops, Ecommerce, SaaS/AI, Logistics, Restaurant POS, School, Healthcare). |
| `add-analytics-section`    | Add a modern analytics & charts section with metrics cards to an existing page.                 |
| `create-auth-flow`         | Generate authentication pages (login, signup, OTP, forgot-password, multi-step onboarding).     |
| `create-data-view`         | Create a data management view with filtering, search, and pagination.                           |
| `customization-guidelines` | Defines which parts of installed blocks can be safely modified (text only).                     |

---

## Example Usage

Once configured, your AI agent can perform tasks like:

> "List all free dashboard shells" -> AI calls `listFreeBlocks(category: "shells")`

> "Give me the installation command for dashboard-shell-01" -> AI calls `getBlockInstall(name: "dashboard-shell-01", packageManager: "pnpm dlx")` and gets the command + import snippet!

> "Create a SaaS analytics dashboard layout" -> AI uses `build-dashboard` and follows `getDashboardLayoutGuidelines`

> "Search for free chart blocks" -> AI calls `searchBlocks(query: "chart", tier: "free")`

---

## Agent Instructions (Claude / Cursor / Windsurf)

If you are using Claude Projects, Cursor, or Windsurf, we have prepared a set of instructions you can copy-paste to make your AI use this MCP Server flawlessly. See [claude-instructions.md](claude-instructions.md).

## Credits

Created by [shadcndashboard](https://shadcndashboard.dev).

[MIT](LICENSE)