MCP Server

The Panda 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. Panda'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
• Inspect configured conditions, animations, and style compositions
• Audit source usage and find unused tokens, recipes, patterns, and keyframes

Quick Start

1. Add the MCP Server

Add the Panda MCP server to your AI client's MCP configuration:

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

For VS Code, use the servers key instead of mcpServers.

2. Use with Your AI Assistant

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

• "What color tokens are available in my design system?"
• "Show me the button recipe variants"
• "What text styles are available?"
• "What breakpoints are defined?"

CLI Commands

The MCP server is distributed as @pandacss/mcp. It is usually started by your AI client, but you can also run it directly with npx, pnpm dlx, or your package manager's equivalent one-off package runner.

Start the MCP server manually (usually not needed - clients start it automatically).

pnpm dlx @pandacss/mcp
 
# With custom config path
pnpm dlx @pandacss/mcp --config ./panda.config.ts
 
# Specify working directory
pnpm dlx @pandacss/mcp --cwd ./my-project

Supported AI Clients

The MCP server can be used with AI assistants that support local stdio MCP servers:

Available Tools

The MCP server exposes these tools to AI assistants:

get_usage_report scans files matching your configured include and exclude paths on each call. Its optional scope accepts all (the default), tokens, recipes, utilities, patterns, or keyframes.

Reports include usage counts, source locations, unused configured names, and diagnostics. Token reports also include raw values and token suggestions; recipe reports include variant usage. Reports with file-read errors or JavaScript parse errors are returned as MCP tool errors and may be incomplete. Other tools query your resolved design-system configuration.

Configuration

For most MCP clients, use this configuration:

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

The server automatically loads your panda.config.ts from the current working directory when started.

Claude

Create .mcp.json in your project root:

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

Cursor

Create .cursor/mcp.json:

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

VS Code

Create .vscode/mcp.json:

{
  "servers": {
    "panda": {
      "command": "npx",
      "args": ["-y", "@pandacss/mcp"]
    }
  }
}

Custom Config Path

If your Panda config is not in the default location, specify it explicitly:

{
  "mcpServers": {
    "panda": {
      "command": "npx",
      "args": ["-y", "@pandacss/mcp", "--config", "./path/to/panda.config.ts"]
    }
  }
}

Example Interactions

Here are some example prompts you can use with AI assistants once MCP is configured:

Exploring Tokens

The AI will use get_tokens with category: "spacing" to show you all spacing values.

Understanding Recipes

The AI will use get_recipes with name: "button" to show variants and usage.

Finding unused tokens

The AI will use get_usage_report with scope: "tokens" to show token usage and unused configured tokens.

Auditing patterns and animations

The AI will use get_usage_report with scope: "patterns" to show pattern usage and source locations. Use scope: "keyframes" to audit animation references, or scope: "all" for all five usage categories.

Checking Conditions

The AI will use get_conditions to show all available breakpoints.

Troubleshooting

Server Not Starting

If the MCP server fails to start:

1. Ensure Panda CSS is installed: pnpm add -D @pandacss/dev
2. Verify you have a valid panda.config.ts in your project
3. Check that npx -y @pandacss/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 scans no files

Check that the include paths in panda.config.ts cover your source files and that the MCP server starts from your project directory. Files matching exclude are not scanned.