# BrixUI MCP Server

A production-ready [Model Context Protocol](https://modelcontextprotocol.io/) server for the **BrixUI Design System V1.2**. Connects AI clients — Claude, ChatGPT, Cursor, Windsurf, Roo Code, Cline, and any MCP-compatible client — directly to your Figma components, design tokens, and variables.

---

## What it does

| Capability | Details |
|---|---|
| **List components** | Browse all 274+ components organized by category |
| **Search components** | Fuzzy search by name, category, or description |
| **Component details** | Full node metadata, auto-layout, variants, fills, effects |
| **Design tokens** | Colors, spacing, border radius, typography via Variables API |
| **MCP Resources** | `brixui://components`, `brixui://tokens`, `brixui://colors`, `brixui://typography` |

---

## Requirements

- Node.js 20+
- A [Figma Personal Access Token](https://www.figma.com/settings)

---

## Installation

### Global install

```bash
npm install -g brixui-mcp-server
```

### Or run without installing

```bash
npx brixui-mcp-server
```

---

## Environment Setup

```bash
export FIGMA_PERSONAL_ACCESS_TOKEN=your_figma_token_here
```

To use a different Figma file (optional):

```bash
export BRIXUI_FILE_KEY=your_custom_file_key
```

The default BrixUI file key is `6Gvd4zkjc7K7RdRxkRF5wP`.

Create a `.env` file for local development:

```bash
cp .env.example .env
# edit .env and add your token
```

---

## Client Configuration

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "brixui": {
      "command": "npx",
      "args": ["brixui-mcp-server"],
      "env": {
        "FIGMA_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "brixui": {
      "command": "brixui-mcp-server",
      "env": {
        "FIGMA_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### ChatGPT Desktop

In ChatGPT Desktop → Settings → MCP Servers → Add Server:

```json
{
  "name": "BrixUI Design System",
  "command": "npx",
  "args": ["brixui-mcp-server"],
  "env": {
    "FIGMA_PERSONAL_ACCESS_TOKEN": "your_token_here"
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "brixui": {
      "command": "npx",
      "args": ["brixui-mcp-server"],
      "env": {
        "FIGMA_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Roo Code

Edit your Roo Code MCP config (`~/.roo/mcp.json` or the workspace `.roo/mcp.json`):

```json
{
  "mcpServers": {
    "brixui": {
      "command": "npx",
      "args": ["brixui-mcp-server"],
      "env": {
        "FIGMA_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Windsurf / Cline / other MCP clients

Any client that supports stdio MCP servers can use:

```json
{
  "command": "npx",
  "args": ["brixui-mcp-server"],
  "env": {
    "FIGMA_PERSONAL_ACCESS_TOKEN": "your_token_here"
  }
}
```

---

## Available Tools

| Tool | Description |
|---|---|
| `list_brix_components` | List all components grouped by category |
| `search_brix_components` | Search by keyword with optional category filter |
| `get_brix_component_details` | Full details for a component by node ID |
| `get_brix_design_tokens` | All color, spacing, radius, and typography tokens |

## Available Resources

| URI | Description |
|---|---|
| `brixui://components` | Full component catalog in plain text |
| `brixui://tokens` | All design tokens |
| `brixui://colors` | Color variables with hex values |
| `brixui://typography` | Typography scale |

---

## Example Prompts

```
Show all button components from BrixUI
```

```
Search for card components in BrixUI
```

```
Get the full details of BrixUI component with nodeId 1958:62429
```

```
What are all the color tokens in BrixUI? Generate a Tailwind config from them.
```

```
Show me the spacing scale from BrixUI and generate CSS custom properties for it
```

```
Explain the auto-layout structure of this BrixUI navigation component: <nodeId>
```

```
Generate a React component using BrixUI design tokens for a pricing card
```

```
What typography styles does BrixUI use? Create a matching Tailwind typography config.
```

---

## Development

```bash
git clone https://github.com/multicomak/BrixUI-MCP.git
cd BrixUI-MCP
npm install
cp .env.example .env
# add your FIGMA_PERSONAL_ACCESS_TOKEN to .env

npm run dev     # watch mode
npm run build   # production build
npm run typecheck  # type checking only
```

---

## Architecture

```
src/
├── index.ts              # MCP server, tools, resources wiring
├── figma/
│   ├── client.ts         # Figma REST API client
│   ├── types.ts          # Full TypeScript types for all Figma structures
│   └── cache.ts          # In-memory cache (5-min TTL)
├── tools/
│   ├── listComponents.ts
│   ├── searchComponents.ts
│   ├── componentDetails.ts
│   └── designTokens.ts
├── resources/
│   ├── components.ts
│   ├── tokens.ts
│   └── typography.ts
├── utils/
│   ├── env.ts            # Token validation and env reading
│   └── logger.ts         # Clean stderr logging
└── constants/
    └── config.ts         # Base URLs, defaults, TTL
```

---

## License

MIT