@atomixstudio/mcp

MCP (Model Context Protocol) server and CLI for Atomix Design System. Query and sync design tokens from AI coding tools (Cursor, Claude Desktop, Windsurf, etc.) or from the command line.

Version: 1.0.28 — Sync to Figma: removes variables/styles not in payload (same collections only); color scopes (Bg = frame fill only, Action/Feedback = all fill); update-or-create for paint/text/effect styles to avoid duplicates; change summary in sync response; instructions AI-tool agnostic.

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: atomix.studio/ds/[ds-id]
5. Your access token: Export modal or Settings → Regenerate Atomix access token (required for MCP)

MCP Server Setup

Connect your AI tool so it can 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>", "--atomix-token", "<your-token>"]
    }
  }
}

Both --ds-id and --atomix-token are required. Get your token from Atomix Studio: Export modal or Settings → Regenerate Atomix access token.

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>", "--atomix-token", "<your-token>"]
    }
  }
}

Windsurf

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

MCP Tools

Once connected, the AI can call these tools:

| 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 | | syncAll(options?) | Sync tokens, AI rules, skills (.cursor/skills/atomix-ds/*), and atomix-dependencies.json. One tool for full project sync. /--sync invokes this. Optional: workspaceRoot (project root so files are written in the repo; else ATOMIX_PROJECT_ROOT env or cwd), output (default ./tokens.css), format (default css), skipTokens (if true, only skills + manifest). | | getRules(topic?) | Get design system governance rules; optional topic: colors, typo, motion, icons, layout, visual | | exportMCPConfig(tool) | Get MCP configuration for different tools | | getSetupInstructions(tool) | Get detailed setup guide | | getDependencies(platform?, stack?) | Get suggested dependencies (icons, fonts, SKILL.md, token files). Optional: platform (web, ios, android), stack (e.g. react, vue, next). Use with /--get-started prompt. | | syncToFigma() | Push design system to Figma (variables, paint styles, text styles, effect styles). Uses built-in bridge + Atomix plugin. If the plugin is not connected, the response includes agentInstruction to connect. Available on all tiers (Free and Pro). |

getDependencies

Returns DS-derived suggestions so the AI can build a "Suggested" vs "Already present" list and, after user approval, install or copy assets.

Parameters (optional): platform — web, ios, or android; stack — e.g. react, vue, next, swift, kotlin.

Returns (JSON):

• iconLibrary — package, nativePackage, and a performance hint (use individual imports; apply the DS icon sizing/weight token when rendering icons).
• fonts — Font family names from typography tokens + hint to link fonts via URL (e.g. Google Fonts); no need to download or add font files to the repo.
• skill — path (e.g. .cursor/skills/atomix-ds/SKILL.md) and content (generic, platform-agnostic SKILL.md).
• tokenFiles — e.g. ["tokens.css", "tokens.json"] with copy instructions.
• meta — dsName, platform, stack, designSystemVersion, designSystemExportedAt. Use designSystemVersion to compare with skill frontmatter atomixDsVersion and suggest syncAll when the design system is newer.

If the design system is unavailable, the tool may fail; the client should tell the user the design system could not be reached.

syncAll

syncAll is the single sync tool: tokens file, AI rules, skills (.cursor/skills/atomix-ds/SKILL.md), and atomix-dependencies.json. The manifest records icon library, font families, and paths. The /--sync prompt invokes it. All paths are resolved under a project root so files are written inside the repo (committable). Project root is: workspaceRoot argument → ATOMIX_PROJECT_ROOT env → process.cwd(). Optional: workspaceRoot (absolute path to repo root), output (default ./tokens.css), format (default css), skipTokens (if true, only writes skills and manifest).

Skill versioning: Synced skills get frontmatter atomixDsVersion and atomixDsExportedAt (from the design system at sync time). The manifest’s skills.syncedAtVersion matches. The AI can compare the skill’s atomixDsVersion to getDependencies’ meta.designSystemVersion; if the design system is newer, it can suggest running syncAll to update.

MCP Prompts

Run these prompts from your AI tool (e.g. /--hello, /--get-started):

| Prompt | Description | |--------|-------------| | /--hello | Get started — overview, tokens, essential commands (including /--sync-to-figma). Run this first. | | /--get-started | Get started with design system in project. Three phases; creates files only after you approve. | | /--rules | Governance rules for your AI tool (Cursor, Copilot, Windsurf, etc.). | | /--sync | Sync tokens, AI rules, skills files, and dependencies manifest (icons, fonts). Use /--refactor to migrate deprecated tokens. | | /--refactor | Migrate deprecated tokens in codebase. Run after /--sync. | | /--sync-to-figma | Push design system to Figma. Requires bridge + Atomix plugin; see Sync to Figma below. Available on all tiers (Free and Pro). |

--get-started (get started)

The /--get-started prompt suggests dependencies for your design system so you can get up and running quickly. It does not install anything by default; the AI presents a list and asks before making changes.

Flow (phased instructions):

1. Resolve platform and stack — Infer from the project (e.g. package.json, build.gradle) or ask the user if the project gives no hint (e.g. blank repo). Do not assume web or any default.
2. Get suggested dependencies — Call getDependencies(platform, stack). If the call fails, tell the user the design system could not be reached and stop.
3. Scan codebase and build suggestion list — Scan for package.json (or equivalent), existing skill path, token files, font/icon usage. Build Suggested dependencies (from getDependencies minus what's present) and Already present. Do not install or copy anything in this phase.
4. Present list and ask before install — Reply with "Suggested dependencies: …" and "Already present: …" and state: "Do not install or copy anything until you confirm. Would you like me to install or add these?" Only perform steps the user approves.
5. Optional: suggest global typeset — If the project has no global styles that use the design system tokens, offer to build a full typeset (Display, Heading, body, caption) from the DS typography tokens via getToken/listTokens, including fontFamily, fontSize, fontWeight, lineHeight, letterSpacing—not just font imports.
6. Report what was created — After any install/copy steps, list what was created or updated (e.g. "Installed: lucide-react. Added: .cursor/skills/atomix-ds/SKILL.md. Synced: tokens.css.").

SKILLs: The get-started flow suggests adding a generic SKILL at .cursor/skills/atomix-ds/SKILL.md (coding-platform agnostic; call getRules for governance rules). Run /--sync to write the skill; .rules files (e.g. .cursorrules) are no longer written.

Sync to Figma

/--sync-to-figma (or the syncToFigma tool) pushes your design system into the open Figma file: color variables, paint styles, number variables (spacing, radius, borders, sizing, breakpoints), text styles, and shadow effect styles. The Figma bridge runs inside this MCP server (no separate process). You only need the Atomix Figma plugin and "Connect to Cursor" (no Figma REST API or token).

Tier: Sync to Figma is available on all tiers (Free and Pro).

Flow:

1. Plugin not connected? The tool checks first. If the plugin is not connected, the response includes bridgeNotRunning, agentInstruction, and userInstruction. Ensure Cursor has this MCP server running, then in Figma run the Atomix plugin and click Connect to Cursor, then call syncToFigma again.
2. Only if that fails should the user check MCP configuration and plugin connection manually.

User steps (when needed):

1. Ensure MCP is running — Cursor should have this MCP server configured and running (the bridge is built in; no separate bridge process).
2. Install and run the Atomix plugin — In Figma: Open Plugins and run the Atomix plugin (Atomix Token Extractor). If it's not installed yet, install it from the Figma Community or your team's plugin library, then run it.
3. Connect — In the plugin UI, tap Connect to Cursor and wait until the status shows "Connected".
4. Run Sync to Figma again.

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

Example Usage (MCP)

Once MCP is connected, you can say:

"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' }}"

CLI

Use the CLI when you prefer commands over the AI, or in scripts/CI.

Quick Start (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

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

File structure: The output file (e.g., tokens.css) is completely rewritten on each sync. Preserved: CSS custom properties (variables). Lost: regular CSS rules (selectors, classes, media queries). Keep your tokens file separate from custom CSS (e.g. use custom.css for custom styles).

heyatomix init

Create a .atomixrc config file:

npx heyatomix init

Creates:

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

CLI Options

| Option | Description | |--------|-------------| | --ds-id | Design system ID (or set in .atomixrc) | | --atomix-token | Access token (required for MCP; from Export modal or Settings → Regenerate) | | --api-base | API base URL (default: https://atomix.studio). Use only for self-hosted instances. | | --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, scss, less, json, ts, js
Native: swift, kotlin, dart

All formats include light and dark mode values.

AI Rules Files (CLI)

By default, sync also updates AI rules files:

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

Example Usage (CLI)

npx heyatomix sync

Package Aliases

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

Troubleshooting

MCP shows "requires authentication" or no tools: Add both --ds-id and --atomix-token to your MCP server args. Get your token from Atomix Studio (Export modal or Settings → Regenerate Atomix access token), then restart your IDE.

MCP shows old prompts or tools after updating: Your IDE or npx may be using a cached version. Quit the IDE, clear the npx cache (rm -rf ~/.npm/_npx on macOS/Linux, or delete the _npx folder inside your npm cache directory), then reopen the IDE and reconnect the MCP server.

Links

• Atomix Studio
• MCP Protocol

License

MIT