@snowflake/stellar-mcp

An MCP (Model Context Protocol) server for Stellar Design System.

MCP servers provide building blocks for adding context to language models:

• Tools (functions): Executable functions that allow models to perform actions or retrieve information
• Resources (data): Structured data or content that provides additional context to the model
• Prompts (templates): Pre-defined templates or instructions that guide language model interactions

This server makes Stellar foundations, design tokens, components, icons, and usage guidelines available to AI apps and agents, enabling AI systems to reason about, generate, and validate UI using Stellar Design System consistently and correctly.

What it can do

With the Stellar MCP Server enabled, designers and developers can use AI to build consistent interfaces with Stellar. It enables AI assistants to:

• Search and discover components
  Find components by name, description, or functionality, and access detailed documentation including props, examples, and usage guidelines.

• Work with design tokens
  Search for and validate tokens for specific CSS properties, ensuring the correct token category is used and avoiding hardcoded values.

• Find icons and assets
  Search across icons, pictograms, and illustrations, and retrieve component names and import paths directly in your workflow.

• Migrate from Core UI
  Get component mappings, migration guides, and conversion patterns. Find Stellar equivalents for Core UI components with usage examples.

• Follow content guidelines
  Access product writing standards for clear, consistent UI content, including style rules and error-messaging best practices.

Why it matters

Stellar MCP Server makes design intent and specs accessible where development happens in AI-assisted coding workflows.

• For designers
  Design decisions (naming, tokens, component patterns) carry through into implementation

• For developers
  Reduce context switching — fetch component specs, token values, and migration guides programmatically where you work

• For teams
  A workflow that connects design and development through AI, ensuring generated code aligns with your actual design system

Pre-installed repositories

The Stellar MCP server is already enabled in the following repositories. If you work in one of these, no installation is needed — just open the project in Cursor and the MCP server is available automatically.

| Repository | Description | | ------------------------------------------------------- | ---------------------------- | | snapps (snowflake-eng/snapps) | Main Snowflake application | | design-prototype (snowflake-eng/design-prototype) | Design prototyping workspace |

How to verify it's working:

1. Open the project in Cursor
2. Open the Command Palette (Cmd+Shift+P) and run "MCP: List Servers"
3. Look for Stellar with a green status indicator
4. Or simply ask the AI about a Stellar component — for example, "What props does the Button component have?"

Installation (other workspaces)

If you're working in a repository that doesn't already include the Stellar MCP server, you can install it manually.

Install script (recommended)

Recommended for most users, especially non-engineering roles without Artifactory access. The script downloads a pre-built copy of the MCP server from stellar.snowflake.com:

curl -fsSL https://stellar.snowflake.com/install-mcp | bash

Via npm (Snowflake engineers)

If you have access to Snowflake's Artifactory npm registry, you can install directly:

npm install @snowflake/stellar-mcp@latest

Usage

With Cursor IDE

Add to your MCP settings in Cursor:

{
  "mcpServers": {
    "Stellar Design System": {
      "command": "npx",
      "args": ["-y", "@snowflake/stellar-mcp@latest"]
    }
  }
}

With Claude Desktop

Use the Claude Code CLI to add the server:

claude mcp add stellar npx -y @snowflake/stellar-mcp@latest

Available tools

Tools are functions that a model can call to perform actions and return results. Stellar offers the following tools (listed here by category for readability).

Tool naming patterns:

• query_* - Returns collections of items for browsing/discovery, with optional filtering and search
• get_* - Returns detailed information about a specific item (for tokens, absence of metadata means invalid)
• find_* - Returns targeted results (for example, token for CSS property)

Documentation

| Tool | What it does | Parameters | | ------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | query_docs | List available docs IDs (no query), or filter docs by query | query (optional)limit (optional, default: 25, query mode only) | | get_doc | Get one documentation page by ID | id: docs ID from query_docs (for example guide:core-ui-migration, foundation:spacing, page:about-get-started-test, page:components-button-code) |

Components

| Tool | What it does | Parameters | | ------------------ | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | query_components | List components (optionally by category) or search by query (optionally include related alternatives) | query (optional)category (optional, list mode)limit (optional, search mode, default: 10)include_related (optional, search mode, default: false)related_limit (optional, search mode, default: 3) | | get_component | Get component details, links, and optional docs content | name: Button, Dialoginclude_docs (optional, default: false)docs_section (optional, default: all): code, examples, usage, all | | query_migration | List Core UI → Stellar mappings or find target for a specific component | component (optional): LoadingIndicator, SidePanel, Typeaheadfilter (optional, list mode): dialog, button |

Icons and assets

| Tool | What it does | Parameters | | ------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | query_icons | List icons/pictograms/illustrations, or search by name when query is provided | query (optional): arrow, chart, usertype (optional, default: all): icon, pictogram, illustration, all | | get_icon | Get info for a specific icon | name: ArrowRightIcon, arrow-right, ChartPictogram |

Design tokens

| Tool | What it does | Parameters | | -------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | query_tokens | Browse token categories (no filters), or query tokens with optional category/query filters and pagination | category (optional): category name (for example: semantic gap, semantic size, radius)query (optional): spacing, 16px, gap, borderlimit (optional, default: 25)offset (optional, default: 0) | | get_token | Get exact token details by name (also validates — no metadata means invalid; returns suggestions if missing) | id: tokens['space-gap-md'], tokens['color-text'], legacyBaltoTheme.reusableTextPrimary | | find_token_for_css | Find the right token category/prefix for a CSS property | css_property: gap, marginBottom, paddingLeft, borderRadiuslimit (optional, default: 10)include_all (optional, default: false) |

Available resources

Resources are read-only, addressable context (by URI) that an MCP client can fetch and provide to a model as needed.

| Resource | What it does | | -------------------------------- | ---------------------------------------------------------------------- | | stellar://figma/component-keys | Figma component keys for programmatic instantiation via the Plugin API |

Available prompts

Prompts are reusable prompt templates that MCP clients can invoke to inject specialized instructions into the conversation. Unlike tools, prompts don't execute code—they return pre-authored guidance that shapes how the AI approaches a task.

| Prompt | What it does | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | review-chart | Evaluates existing data visualizations for correctness, accessibility, and storytelling. Takes code, screenshots, or Figma designs as input and produces structured feedback with severity-rated issues, engineering specs, and actionable fixes. Supports individual charts and full dashboards. | | select-chart | Recommends the right Stellar chart component for a dataset and goal. Maps fields and analytic tasks to @stellar/charts components with rationale, key props, and pitfalls. Does not implement full JSX (use get_component + examples; a create-chart prompt is planned) or themed Vega/Vega-Lite specs. | | explain-chart | Produces narrative framing for charts and dashboards: insight headlines, subtitles, chart titles, accessibility strings, callouts, annotation copy, and tooltip story order. Does not choose chart types (select-chart) or run severity-based review (review-chart). |

stellar-charts

Transforms the AI into a data visualization expert when users need chart reviews or implementation help. Activates when:

• User uploads a chart image or screenshot
• User shares a Figma file containing charts
• Code contains chart components (<Bar>, <Line>, <Area>, <Scatter>, <Donut>, vega-lite)
• User asks for help creating or improving a data visualization
• User asks which chart type or Stellar component fits their data
• User asks for chart titles, headlines, callouts, or how to phrase the insight

Capabilities:

• Drafts narrative and accessibility copy around visualizations (explain-chart)
• Selects chart types and Stellar components from data shape and goals (select-chart)
• Reviews visual encoding and chart type appropriateness
• Audits accessibility (color contrast, colorblind safety, screen reader support)
• Evaluates data storytelling and context
• Generates structured handoff documentation with checklists for designers and specs for engineers

Supporting documentation (accessible via get_doc):

• guide:stellar-charts-severity-levels - Issue severity definitions
• guide:stellar-charts-review-checklists - Review area checklists
• guide:stellar-charts-communication-style - Feedback tone and style
• guide:stellar-charts-feedback-templates - Structured feedback formats
• guide:stellar-charts-handoff-templates - Design-to-engineering handoff formats
• guide:stellar-charts-implementation - Stellar Charts implementation patterns
• guide:stellar-charts-patterns - Common chart patterns and when to use them

Example queries

Try these queries to explore the capabilities of the Stellar MCP Server:

Documentation

• "What are Stellar's accessibility guidelines?"
• "Show me the typography foundation"
• "What are the content writing guidelines for error messages?"
• "How do I write responsive styles with StyleX?"

Components

• "What components does Stellar have for displaying user feedback?"
• "Show me how to use the Dialog component"
• "What's similar to a Menu component?"
• "List all navigation components"
• "What's the Stellar equivalent of Core UI's LoadingIndicator?"
• "How do I migrate a SidePanel from Core UI?"

Icons and assets

• "Find icons related to 'arrow'"
• "How do I import the ChartPictogram?"
• "List all available pictograms"

Design tokens

• "What token should I use for gap in CSS?"
• "Search for spacing tokens with 16px"
• "Is tokens['space-gap-lg'] a valid token?"
• "Show me all radius tokens"

Real-world scenarios

• "I need to build a form with validation feedback. What components and tokens should I use?"
• "Help me create a card layout with proper spacing tokens"

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run in development mode
pnpm dev

# Start the server
pnpm start

If you want to develop new prompts you can do so with a fully built MCP. Once the MCP is built just add files to prompts/, name the skill/workflow PROMPT.md, and restart the MCP server.

Embedding model (semantic search)

Semantic search uses the Xenova/bge-small-en-v1.5 model. The model is vendored into models/ and committed to the repo so that builds and the runtime server never download it from the Hugging Face Hub. This keeps CI hermetic (no intermittent network failures) and lets the server run offline or behind a firewall.

To add or upgrade the model:

# Downloads the model files into models/ with retry/backoff
pnpm download-model

# Then commit the updated files under models/

The model identity (name and embedding dimension) is defined once in src/model-config.js and shared by scripts/download-model.ts, scripts/build-embeddings.ts, and src/vector-search.ts. When upgrading, update the values there and re-run pnpm download-model and pnpm build-embeddings.

Chart prompt references (maintenance)

When additional MCP chart prompts ship (for example create-chart, style-chart, or migrate-chart), revisit shared reference material so encoding rules stay consistent across prompts:

• Consolidate or cross-link relationship → chart guidance (today split across prompts/review-chart/references/CHART_SELECTION.md, prompts/select-chart/references/DECISION_MATRIX.md, and the component table in prompts/review-chart/prompt.md).
• Pick a single source of truth for numeric constraints (donut slice limits, bar baselines, area stack depth, line vs bar heuristics) and have other prompts link to it instead of duplicating tables.
• Re-scan handoff sections in each chart prompt so they point at the correct next step and do not reference prompts that are not yet in the MCP bundle.

License

Apache-2.0