---
title: MCP Server
description: Expose your Bamboo CSS design system to AI assistants using the Model Context Protocol (MCP).
---

The Bamboo MCP Server allows AI assistants like Claude, Cursor, VS Code Copilot, Windsurf, and Codex to understand and
work with your project's design system. It provides tools for querying tokens, recipes, patterns, conditions, and more.

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI assistants to
external tools and data sources. Bamboo's MCP server exposes your design system through a set of specialized tools that
AI assistants can use to:

- Look up design tokens and their values
- Understand available component recipes and variants
- Query layout patterns and their properties
- Analyze token and recipe usage across your codebase

## Quick Start

### 1. Initialize MCP Configuration

Run the interactive setup command in your project:

```bash
pnpm bamboo init-mcp
```

This will prompt you to select which AI clients to configure:

```
◆  Bamboo MCP Setup
│
◆  Select AI clients to configure:
│  ◻ Claude (.mcp.json)
│  ◻ Cursor (.cursor/mcp.json)
│  ◻ VS Code (.vscode/mcp.json)
│  ◻ Windsurf (.windsurf/mcp.json)
│  ◻ Codex (.codex/mcp.json)
```

### 2. Use with Your AI Assistant

Once configured, your AI assistant will automatically have access to Bamboo CSS tools. You can ask questions like:

- "What color tokens are available in my design system?"
- "Show me the button recipe variants"
- "Which tokens are unused in my codebase?"
- "What breakpoints are defined?"

## CLI Commands

### init-mcp

Initialize MCP configuration for one or more AI clients.

```bash
# Interactive mode - select clients from a list
pnpm bamboo init-mcp

# Configure specific clients directly
pnpm bamboo init-mcp --client claude,cursor

# Specify working directory
pnpm bamboo init-mcp --cwd ./my-project
```

| Flag               | Description                               |
| ------------------ | ----------------------------------------- |
| `--client <names>` | AI clients to configure (comma-separated) |
| `--cwd <path>`     | Current working directory                 |

### The server itself

The server ships as its own package, `@bamboocss/mcp`, and is started through `npx` rather than through the Bamboo CLI.
That is what the generated config does, so you rarely run it by hand:

```bash
npx -y @bamboocss/mcp

# With custom config path
npx -y @bamboocss/mcp --config ./bamboo.config.ts

# Specify working directory
npx -y @bamboocss/mcp --cwd ./my-project
```

| Flag                  | Description                |
| --------------------- | -------------------------- |
| `--config, -c <path>` | Path to Bamboo config file |
| `--cwd <path>`        | Current working directory  |
| `--help, -h`          | Show usage and exit        |

It is packaged separately because the Model Context Protocol SDK brings an HTTP server and a JOSE implementation with it
– around 18 MB, several times the weight of Bamboo's own CSS toolchain. Keeping it out of `@bamboocss/dev` means a
project only downloads it if an AI client actually starts the server.

`bamboo mcp` no longer exists. If you configured a client before this change, re-run `bamboo init-mcp` to rewrite the
config.

## Supported AI Clients

The MCP server supports the following AI assistants:

| Client   | Config Path          | Description                    |
| -------- | -------------------- | ------------------------------ |
| Claude   | `.mcp.json`          | Claude Code and Claude Desktop |
| Cursor   | `.cursor/mcp.json`   | Cursor IDE                     |
| VS Code  | `.vscode/mcp.json`   | VS Code with Copilot           |
| Windsurf | `.windsurf/mcp.json` | Windsurf IDE                   |
| Codex    | `.codex/mcp.json`    | OpenAI Codex CLI               |

## Available Tools

The MCP server exposes these tools to AI assistants:

| Tool                  | Description                                                         | Input                                     |
| --------------------- | ------------------------------------------------------------------- | ----------------------------------------- |
| `get_tokens`          | Get design tokens with values, CSS variables, and usage examples    | `category?` - filter by token category    |
| `get_semantic_tokens` | Get semantic tokens with conditional values (dark mode, responsive) | `category?` - filter by token category    |
| `get_color_palette`   | Get the complete color palette                                      | -                                         |
| `get_recipes`         | Get component recipes with variants and default values              | `name?` - filter by recipe name           |
| `get_patterns`        | Get layout patterns with properties and usage examples              | `name?` - filter by pattern name          |
| `get_conditions`      | Get all conditions (breakpoints, pseudo-classes, color modes)       | -                                         |
| `get_keyframes`       | Get keyframe animations defined in the theme                        | -                                         |
| `get_mixins`          | Get the named style bundles defined in `theme.mixins`               | -                                         |
| `get_config`          | Get the resolved Bamboo CSS configuration                           | -                                         |
| `get_usage_report`    | Analyze token/recipe usage across the codebase                      | `scope?` - `'all'`, `'token'`, `'recipe'` |

The `get_usage_report` tool is particularly useful for auditing your design system, identifying unused tokens/recipes,
and finding missing definitions.

## Generated Configuration

When you run `bamboo init-mcp`, the following configuration is generated for each selected client:

```json
{
  "mcpServers": {
    "bamboo": {
      "command": "npx",
      "args": ["-y", "@bamboocss/mcp@<version>"]
    }
  }
}
```

The version is pinned to the Bamboo you generated it with, so the server reads your design system through the same
release that defines it – re-run `bamboo init-mcp` after upgrading. The server loads your `bamboo.config.ts` from the
current working directory when started.

## Manual Configuration

If you prefer to configure MCP manually, create the config file your client expects — the paths are in the table above —
with these contents. Replace `<version>` with your installed Bamboo version:

```json
{
  "mcpServers": {
    "bamboo": {
      "command": "npx",
      "args": ["-y", "@bamboocss/mcp@<version>"]
    }
  }
}
```

VS Code is the one exception: `.vscode/mcp.json` names the top-level key `servers` rather than `mcpServers`. Everything
under it is the same.

If your Bamboo config is not in the default location, pass it explicitly:

```json
{
  "mcpServers": {
    "bamboo": {
      "command": "npx",
      "args": ["-y", "@bamboocss/mcp@<version>", "--config", "./path/to/bamboo.config.ts"]
    }
  }
}
```

## Troubleshooting

### Server Not Starting

If the MCP server fails to start:

1. Ensure Bamboo CSS is installed: `pnpm add -D @bamboocss/dev`
2. Verify you have a valid `bamboo.config.ts` in your project
3. Check that `npx -y @bamboocss/mcp` runs without errors

### Tools Not Available

If tools aren't showing up in your AI assistant:

1. Restart the AI assistant after adding the MCP configuration
2. Verify the config file is in the correct location
3. Check the AI assistant's MCP documentation for any additional setup steps

### Usage Report Empty

If `get_usage_report` returns empty results:

1. Ensure your `include` paths in `bamboo.config.ts` cover your source files
2. Run `pnpm bamboo codegen` to ensure the project is properly set up
3. Verify files contain Bamboo CSS usage (css(), cva(), etc.)
