@atomixstudio/mcp

MCP (Model Context Protocol) server and CLI for Atomix Design System. Query and sync design tokens directly from AI coding tools like Cursor, Claude Desktop, Windsurf, and more.

Quick Start (CLI)

The easiest way to use Atomix is via the CLI:

# Sync tokens + AI rules (default behavior)
npx heyatomix sync

# Sync tokens only (skip AI rules)
npx heyatomix sync --no-rules

# Create config file
npx heyatomix init

Getting Your Credentials

1. Go to Atomix Studio
2. Sign in and create/access your design system
3. Click Publish to make your DS available via API
4. Your ds-id is in the URL: atomixstudio.eu/ds/[ds-id]

CLI Commands

heyatomix sync

Sync design tokens and AI rules to your project. Both tokens and AI guidance rules sync by default since the rules reference tokens.

npx heyatomix sync                    # Sync tokens + AI rules
npx heyatomix sync --no-rules         # Sync tokens only
npx heyatomix sync -o src/tokens.css  # Custom output path
npx heyatomix sync --format scss      # Output as SCSS
npx heyatomix sync -y                 # Auto-confirm changes

heyatomix init

Create a .atomixrc config file:

npx heyatomix init

This creates:

{
  "dsId": "your-design-system-id",
  "output": "./tokens.css",
  "format": "css"
}

CLI Options

| Option | Description | |--------|-------------| | --ds-id | Design system ID (or set in .atomixrc) | | --api-key | API key for private design systems | | --output, -o | Output file path [./tokens.css] | | --format | Output format (see below) | | --no-rules | Skip syncing AI rules (tokens + rules sync by default) | | --rules-dir | Directory for rules files [project root] | | -y, --yes | Auto-confirm changes |

Output Formats

Web:

• css — CSS custom properties (:root { --var: value })
• scss — CSS vars + SCSS variables ($var: value)
• less — CSS vars + Less variables (@var: value)
• json — Raw token JSON
• ts — TypeScript with types
• js — JavaScript module

Native:

• swift — Swift/SwiftUI for iOS
• kotlin — Kotlin/Compose for Android
• dart — Dart for Flutter

All formats include light and dark mode values.

MCP Server Setup

For AI tools to query your design system directly:

Cursor IDE

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "my-design-system": {
      "command": "npx",
      "args": ["@atomixstudio/mcp@latest", "--ds-id", "<your-ds-id>"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-design-system": {
      "command": "npx",
      "args": ["@atomixstudio/mcp@latest", "--ds-id", "<your-ds-id>"]
    }
  }
}

Windsurf

Create .windsurf/mcp.json in your project root (same format as Cursor).

MCP Tools

Once connected, AI tools can use these:

| Tool | Description | |------|-------------| | getToken(path) | Get a specific token by path (e.g., colors.brand.primary) | | listTokens(category) | List all tokens in a category | | searchTokens(query) | Search tokens by name or value | | validateUsage(value) | Check if a hardcoded value should use a token | | syncTokens(options) | Sync tokens to a local file | | getAIToolRules(tool) | Generate AI coding rules for your design system | | exportMCPConfig(tool) | Get MCP configuration for different tools | | getSetupInstructions(tool) | Get detailed setup guide |

Token Categories

• colors — Brand, background, text, icon, border, action, feedback (light + dark)
• typography — Font families, sizes, weights, line heights
• spacing — Scale tokens (xs, sm, md, lg, xl, etc.)
• sizing — Component heights, icon sizes
• shadows — Elevation scale
• radius — Border radius scale
• borders — Border width tokens
• motion — Duration and easing tokens
• zIndex — Layer tokens

AI Rules Files

By default, sync also updates AI rules files based on which AI tools you use:

| File | AI Tool | |------|---------| | .cursorrules | Cursor | | .windsurfrules | Windsurf | | .clinerules | Cline | | .continuerules | Continue | | .github/copilot-instructions.md | GitHub Copilot | | AI_GUIDELINES.md | Generic |

The rules include your design system's governance guidelines and token usage instructions.

Example Usage

CLI:

npx heyatomix sync

Natural language (via MCP):

"Sync my design tokens to tokens.css"

"What color tokens are available?"

"Use the correct spacing token for 16px padding"

"Validate this: style={{ backgroundColor: '#007061' }}"

Package Aliases

| Package | Description | |---------|-------------| | heyatomix | Recommended CLI (e.g., npx heyatomix sync) | | @atomixstudio/mcp | Full MCP server + CLI | | atomix-sync | Legacy alias (deprecated) |

Links

• Atomix Studio
• MCP Protocol

License

MIT