Skip to main content
Glama
systembridge-mcp

systembridge-mcp

by teyepe

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.

License: MIT TypeScript MCP


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: ds-mcp

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

Area

Tools

Designer intelligence

plan_flow, audit_design, analyze_ui

Token management

search_tokens, validate_tokens, transform_tokens

Semantic tokens

scaffold_semantics, audit_semantics, analyze_coverage, describe_ontology

Color & accessibility

generate_palette, map_palette_to_semantics, check_contrast

Themes & brands

list_brands, resolve_brand, list_themes, resolve_theme, diff_brands, diff_themes

Scales

analyze_scales, generate_scale, suggest_scale, derive_density_mode, audit_scale_compliance, generate_fluid_scale

Migration

analyze_topology, audit_figma_usage, generate_refactor_scenarios, execute_migration

Figma

extract_figma_tokens, validate_figma_tokens, generate_component_docs

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

Guide

Description

Getting Started

Full installation, config options, troubleshooting

Setup by Client

Per-client setup (Cursor, VS Code, Claude Desktop, Claude Code)

Agent Instructions

Optional AI usage guidance and rule templates

Local Testing

Test with npm link without absolute paths

For Designers

Designer workflow, example prompts, no-code usage

For Developers

CLI, MCP API, extending the server, tests, benchmarks

Features

Full feature and tool reference

Configuration

Config file, env vars, token paths

Migration System

Risk assessment and scenario generation

Migration Executor

Execution, validation, and rollback

Figma Integration

Figma variable sync and validation

AGENT_HANDOFF

Architecture guide for LLMs and agents


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

Available Tools

37 tools
analyze_coverageA

Show the semantic token coverage matrix — which UX contexts have which property classes covered, and where the gaps are. Displays a table of contexts × property classes with status indicators.

Inputs: pathPrefix.

analyze_scalesA

Analyze existing design token scales (spacing, typography, etc.). Detects mathematical patterns (linear, modular, fibonacci, etc.), identifies outliers, and suggests improvements based on design principles.

Inputs: tokens (required), dimension, compareAgainst.

analyze_topologyA

Analyze token topology with dependency graph, anti-pattern detection, and structure analysis. Shows token relationships, reference chains, isolated tokens, circular dependencies, and common anti-patterns like primitive leakage, naming inconsistencies, and redundant tokens. Includes visual dependency graph (Mermaid), distribution charts, and coverage matrix.

Inputs: pathPrefix, includeGraph, graphMaxDepth, graphMaxNodes, +2 more.

analyze_uiA

Analyze UI elements and colors against the design system. Describe the components you see and the colors used — get back which components are in the system, which colors match existing tokens (using perceptual color distance), and what gaps exist. Useful for reverse-engineering a screenshot or mockup into system terms.

Inputs: components (required), colors, description.

audit_designA

Audit a partial or complete design against the design system. Provide the components used in your design and get a gap analysis: missing tokens, naming issues, accessibility problems, and concrete fixes. Use this before handoff to ensure design-system coverage.

Inputs: components (required), description, checkAccessibility.

audit_figma_usageA

Audit Figma variable usage and cross-reference with local design tokens. Analyzes sync status between Figma variables and local token definitions, identifies unused tokens, missing definitions, and naming discrepancies. Helps maintain consistency between Figma designs and token system. Note: Requires Figma variable data from mcp_figma_get_variable_defs.

Inputs: figmaFileUrl (required), figmaNodeId, figmaVariableDefs.

audit_scale_complianceA

Audit design token scales against accessibility and platform standards. Checks WCAG 2.2 (44px touch targets, 1.5 line height), Material Design (8dp grid), and iOS HIG (8pt grid) compliance.

Inputs: tokens (required), standard, dimension.

audit_semanticsA

Run a comprehensive semantic token audit on your existing token set. Analyzes naming compliance, property-class separation, coverage gaps, scoping violations, accessibility pairing, and suggests migrations. Returns a health score (0-100) and detailed report.

Inputs: skipRules, pathPrefix.

check_contrastA

Check color contrast ratios using WCAG 2.1 and/or APCA algorithms. Two modes: (1) provide explicit foreground + background colors, or (2) scan your token set for all foreground/background pairs and report failures.

Inputs: algorithm, threshold, background, foreground, +1 more.

derive_density_modeA

Derive a new density mode (compact/spacious) from existing tokens. Applies scale factors while respecting WCAG accessibility constraints (44px minimum touch targets). Outputs conditional tokens.

Inputs: sourceTokens (required), targetDensity (required), roundTo, sourceDensity, +2 more.

describe_ontologyA

Explain the semantic token naming model — property classes (CSS targets), semantic intents, UX contexts, interaction states, emphasis modifiers, and the canonical naming formula. Use this to understand how semantic tokens should be structured.

Inputs: no named parameters.

diff_brandsA

Compare two brands side-by-side, showing which tokens differ between them. Optionally resolves both under the same theme.

Inputs: brandA (required), brandB (required), theme, pathPrefix.

diff_themesB

Compare two themes side-by-side and show which tokens differ, which are added, and which are removed.

Inputs: themeA (required), themeB (required), pathPrefix.

execute_migrationA

Execute token migration with automated reference updates, validation, and rollback. Applies scenario phases to token system, updates references across codebase, validates integrity (no broken refs/circular deps), and checks accessibility. DEFAULTS TO DRY RUN for safety - set dryRun:false to apply changes. Creates snapshot before execution for rollback if needed.

Inputs: dryRun, pathPrefix, scenarioId, phaseNumber, +3 more.

extract_figma_tokensA

Extract Figma variables and convert to standardized token formats (W3C, Tokens Studio, Style Dictionary). Takes Figma variable definitions from mcp_figma_get_variable_defs and transforms them into design tokens with proper type inference, collection mapping, and metadata. Useful for syncing Figma variables to your local token system.

Inputs: format (required), includeMetadata (required), figmaVariableDefs (required), collections.

extract_stylesA

Extract design tokens from CSS and SCSS files. Reverse-engineers colors, spacing, typography from stylesheets. Use when project has styles but no design tokens. Scans for CSS custom properties (--var: value) and SCSS variables ($var: value).

Inputs: stylePaths, outputFormat, writeToTokens.

generate_component_docsA

Generate comprehensive component documentation combining local tokens, Figma component data, and design system knowledge. Creates LLM+human-readable markdown with frontmatter, token references, code examples, and accessibility information. Perfect for design-to-development handoffs.

Inputs: format (required), componentNames (required), includeTokenRefs (required), includeCodeExamples (required), +2 more.

generate_fluid_scaleB

Generate fluid/responsive scales using CSS clamp(). Creates viewport-aware tokens that scale between min/max sizes. Based on Utopia fluid typography methodology.

Inputs: maxSize (required), minSize (required), unit, ratio, +4 more.

generate_make_guidelinesA

Generate a structured 'guidelines/' folder for Figma Make. Exports your design system's tokens and component rules into Markdown format that Figma Make's AI can use to understand your system context.

Inputs: outputDir, components.

generate_paletteA

Generate color palettes using pluggable strategies. Supports HSL ramp (built-in), Leonardo (optional), manual hex values, or importing from existing tokens. Returns tonal scales with contrast metadata.

Inputs: scales (required), steps, smooth, strategy, +1 more.

generate_refactor_scenariosA

Generate migration scenarios for token refactoring with risk assessment. Produces 3 approaches (conservative, progressive, comprehensive) with detailed action plans, effort estimates, and risk profiles. Helps plan B→C token migration by comparing trade-offs and recommending best path forward based on readiness.

Inputs: teamSize, approaches, pathPrefix, hoursPerWeek, +1 more.

generate_scaleA

Generate a mathematical scale for design tokens. Supports linear, modular (geometric), exponential, fibonacci, golden ratio, harmonic, and hybrid strategies. Returns token-ready values.

Inputs: strategy (required), base, step, unit, +4 more.

generate_systemB

Generate a new design-token system from a template. Supports color palettes, spacing scales, and full systems. Use dryRun=true to preview first.

Inputs: template (required), dryRun, params, outputDir.

list_brandsA

List all brands defined in config, showing their token paths, token-set overrides, and dimension defaults.

Inputs: no named parameters.

list_dimensionsA

List all variation dimensions (e.g. color-scheme, density) defined in your design-token theming config, with their allowed values and defaults.

Inputs: no named parameters.

list_templatesA

List all available factory templates for generating new token systems. Shows required parameters and built-in algorithm options.

Inputs: no named parameters.

list_themesA

List all named themes defined in config. Each theme is a specific combination of dimension values (e.g. dark + compact).

Inputs: no named parameters.

map_palette_to_semanticsA

Map generated palette scales to semantic tokens using configurable rules. Includes built-in presets for light-mode and dark-mode mappings. Can write output to disk with merge and split strategies.

Inputs: palette (required), rules, dryRun, preset, +5 more.

plan_flowA

Solve 'blank canvas syndrome' — describe a screen, feature, or user problem in plain language and get back suggested UI patterns, component inventories, token surface requirements, and next steps. Perfect for starting a new design or understanding what a feature needs from the design system.

Inputs: description (required), maxPatterns, includeScaffold.

resolve_brandA

Resolve design tokens for a specific brand, optionally combined with a theme. Shows how brand overrides affect the token system. When truncated, offer to fetch more by calling again with limit set to the total count.

Inputs: brand (required), limit, theme, pathPrefix.

resolve_themeA

Resolve the full set of design tokens for a specific theme (or arbitrary coordinate set). Shows how tokens change from the default. When truncated, offer to fetch more by calling again with limit set to the total count.

Inputs: theme (required), limit, pathPrefix.

scaffold_semanticsA

Generate a minimum viable semantic token set from a component inventory. Provide a comma-separated list of components (e.g. 'button, text-input, card, alert') and get properly structured tokens with CSS property class separation, intent coverage, and state completeness.

Inputs: components (required), dryRun, format, outputDir, +6 more.

search_tokensA

Search and discover design tokens by name, type, value, or other criteria. Use this to answer questions like 'What color tokens exist?', 'Find all spacing tokens', or 'Show deprecated tokens'. When results are truncated (e.g. '50 of 200'), offer to fetch more by calling again with limit: . Do not report truncation as a failure.

Inputs: text, type, limit, category, +5 more.

suggest_scaleB

Suggest optimal scale parameters based on design principles. Combines Swiss style, Material Design, iOS HIG, financial UI, and other industry standards to recommend strategy, ratio, base, and constraints.

Inputs: dimension (required), principles (required), useCase.

transform_tokensA

Transform design tokens into platform-specific output files using Style Dictionary. Generates CSS custom properties, SCSS variables, JavaScript modules, iOS/Swift code, Android XML, Compose code, etc. Use dryRun=true to preview without writing files.

Inputs: dryRun, platforms.

validate_figma_tokensA

Validate Figma variables against local token definitions. Checks for naming mismatches, type errors, missing mappings, and value discrepancies. Provides detailed validation report with errors, warnings, and sync status. Use strict mode to fail on any mismatch, or non-strict for warnings only.

Inputs: strict (required), figmaVariableDefs (required).

validate_tokensA

Validate design tokens against configurable rules. Checks naming conventions, value formats, type requirements, deprecated references, and architectural patterns. Returns a structured report with errors, warnings, and suggestions.

Inputs: preset, pathPrefix.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 37 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing dimensions/brands/themes, searching/validating/transforming tokens, auditing various aspects, generating palettes/scales/systems, diffing, and figma integration. Even overlapping areas like audits are differentiated by scope (semantic vs design vs figma usage). No two tools appear to do the same thing.

    Naming Consistency5/5

    Tools follow a consistent verb_noun pattern: list_, search_, validate_, transform_, generate_, audit_, analyze_, etc. All use lowercase snake_case. The naming is predictable and easily understood.

    Tool Count4/5

    37 tools is on the higher side, but the server covers a broad domain: token management, audit, generation, Figma sync, accessibility, documentation, etc. Each tool serves a specific need, and the count is justified by the comprehensiveness. Could be slightly trimmed, but overall reasonable.

    Completeness4/5

    The tool set covers nearly the entire design token lifecycle: creation (generate), reading (list, search, resolve), transformation, validaton, auditing, migration, and scaling. Missing an explicit delete/remove tool, but migration execution can handle removal. Minor gap, but overall very complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes your design system components and tokens to AI agents, preventing duplicate component creation and hardcoded token values.
      6 npm
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A read-only MCP server that provides AI coding agents with a queryable contract for design system tokens, components, patterns, and anti-patterns.
      13 npm
      1
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that connects AI clients to Figma components, design tokens, and variables from the BrixUI Design System, enabling component browsing, searching, and token retrieval.
      4
      4 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives AI assistants structured access to a design system's tokens, components, guidelines, and patterns, enabling them to read, lint, and author design system data.
      1
      MIT