systembridge-mcp: MCP Server for Design Systems

An AI-native Model Context Protocol (MCP) server that gives LLMs and agents deep knowledge of design systems and design tokens, enabling intelligent design system evolution, token analysis, and designer-to-developer handoffs.

What is this?

systembridge-mcp teaches AI assistants (like Claude, GPT, or custom agents) how to work with your design system. Instead of just answering questions about design, the AI can:

• Understand your design tokens: browse, search, and explain color palettes, spacing scales, and typography

• Plan new features: describe what you need ("a login page"), get components and tokens required

• Audit designs before handoff: check if your design has all the tokens it needs, find gaps, verify accessibility

• Match colors and components: upload a screenshot or describe UI, get back what matches your system

• Generate and validate tokens: create palettes, check WCAG contrast, scaffold semantic tokens

• Evolve your system: transform tokens, migrate naming, manage themes and brands

Designers: Think of it as a design system assistant that knows your token library. Ask "what red for error states?" or "what tokens should I apply on this mockup?" — no code required.

Developers: A programmatic interface to design tokens with AI-native tooling for analysis, transformation, and code generation.

Related MCP server: tokensStudioMCP

Quick Start

What you need: Node.js 18+ and an AI assistant that supports MCP (e.g. Claude Desktop, Cursor).

1. Install in your design-token project:

   npm install -D systembridge-mcp

2. Add a config file in your project root (optional; sensible defaults apply):

   // .systembridge-mcp.json or systembridge-mcp.config.json
   { "tokenPaths": ["tokens/**/*.json", "design-tokens/**/*.json"] }

3. Add to your MCP config (e.g. .cursor/mcp.json for Cursor):

   {
     "mcpServers": {
       "systembridge-mcp": {
         "command": "npx",
         "args": ["systembridge-mcp"]
       }
     }
   }

4. Restart your AI assistant. Look for the MCP icon — you should see 32 tools from systembridge-mcp. No path configuration needed when using project-level config.

Next: Getting Started | Setup by Client (Cursor, VS Code, Claude) | Agent Instructions (optional AI guidance).
For local development: TESTING.

Example Conversations

For Designers

"I need to design a dashboard with data tables and stat cards. What components and tokens do I need?"

The AI uses plan_flow to identify UI patterns, list required components, and tell you what token slots to fill.

"I'm using button, text-input, card, and modal. Does my design system cover everything?"

The AI uses audit_design to check for missing tokens, naming issues, and accessibility problems.

"I see a UI with colors #3B82F6, #EF4444, #F3F4F6. Which tokens match?"

The AI uses analyze_ui with perceptual color matching to find the closest tokens.

For Developers

"Generate a brand color palette with hue 220, chroma 0.7, and map it to semantic tokens for light mode."

The AI uses generate_palette + map_palette_to_semantics + check_contrast to create accessible tokens.

"Run a full audit of my design tokens. Check naming, accessibility, and coverage."

The AI uses audit_semantics + analyze_coverage + check_contrast to produce a health report.

"I have legacy tokens that don't follow our naming convention. Help me migrate them safely."

The AI uses analyze_topology → generate_refactor_scenarios → execute_migration to plan and execute the migration.

Features

7 pre-built prompts orchestrate multiple tools: create-token, audit-tokens, design-semantic-tokens, design-color-palette, design-from-scratch, design-handoff-review, component-reference.

Full reference: docs/features.md

Documentation

Contributing

Contributions welcome. Fork, create a feature branch, make your changes, run npm run build, and submit a pull request.

See docs/AGENT_HANDOFF.md for codebase architecture.

License

MIT — see LICENSE. Copyright © 2024–2026 Tasos Dervenagas.

Acknowledgments

Built on Model Context Protocol, Style Dictionary, Leonardo, and WCAG 2.1. Inspired by W3C DTCG, Tokens Studio, and design systems from Primer, Polaris, and Carbon.

Support: GitHub Issues · GitHub Discussions · MCP Discord