MCP Server

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) (opens in a new tab) 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:

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.

# 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

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:

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

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:

Available Tools

The MCP server exposes these tools to AI assistants:

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:

{
  "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:

{
  "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:

{
  "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.)