SDS MCP server

Intro

The SDS MCP server gives MCP-compatible AI tools access to Soracom Design System component data.

Use it when you want an assistant to inspect SDS components, generate SDS HTML, validate existing markup, or build common UI patterns using SDS conventions.

The server is distributed as @soracom/sds-mcp-server through GitHub Packages and runs locally as a stdio MCP server.

Why use SDS MCP Server

SDS has specific component structure, modifier syntax, templates, icons, colors, and accessibility guidance. The MCP server makes that information available to AI tools while they are working in your editor or terminal.

It helps assistants:

Use real SDS components instead of guessing class names.
Generate SDS modifiers in the correct class format.
Check existing HTML for common SDS mistakes.
Discover templates and examples for components.
Build forms and common layouts faster.

For example, SDS modifier classes are separate from the component class. The server can generate this format and flag the older ds-button--primary style as incorrect:

<!-- Correct -->
<button class="ds-button --primary --large"><span>Save</span></button>

<!-- Incorrect -->
<button class="ds-button ds-button--primary ds-button--large"><span>Save</span></button>

Features

The SDS MCP server provides these tools:

Tool	Use
`list_sds_components`	List SDS components, optionally filtered by category.
`get_component_info`	Inspect a component’s description, category, supported modifiers, and templates.
`generate_component_html`	Generate valid HTML for an SDS component with modifiers, content, and attributes.
`get_component_template`	Get pre-built HTML templates for common component patterns.
`list_component_modifiers`	List global SDS modifiers by type, including size, color, variant, state, layout, icon, indent, and gap modifiers.
`validate_sds_html`	Validate SDS HTML and get suggestions for incorrect class formats, invalid modifiers, structure issues, and accessibility concerns.
`create_component_form`	Generate a complete SDS form from field definitions.

The server is backed by SDS component manifests. These manifests describe component identity, valid host elements, modifiers, structure, named parts, default attributes, examples, CSS custom properties, data attributes, and accessibility notes where available.

Prerequisites

Node.js 18+.
A GitHub personal access token with read:packages scope, from an account with access to @soracom/sds-mcp-server.

Authenticate npm with GitHub Packages

Add these lines to your user .npmrc (~/.npmrc, or %USERPROFILE%\.npmrc on Windows):

@soracom:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Then export GITHUB_TOKEN in your shell. You can also paste the token directly in place of ${GITHUB_TOKEN} if you prefer.

Verify the server

Start the server directly with npx:

npx -y @soracom/sds-mcp-server

You should see SDS MCP server running on stdio. Press Ctrl+C to stop it.

Configuring AI tools

Every client runs the same stdio command: npx -y @soracom/sds-mcp-server. Restart the client after changing its config.

VS Code

code --add-mcp '{"name":"sds-server","command":"npx","args":["-y","@soracom/sds-mcp-server"]}'

Or run MCP: Add Server from the Command Palette. Manage servers via MCP: List Servers.

Zed

Add to Zed settings:

{
  "context_servers": {
    "sds-server": {
      "command": "npx",
      "args": ["-y", "@soracom/sds-mcp-server"]
    }
  }
}

Or from the Agent menu, select “Add Custom Server…”.

Codex

codex mcp add sds-server -- npx -y @soracom/sds-mcp-server

Check connection with /mcp inside a session.

Claude Code

claude mcp add --transport stdio sds-server -- npx -y @soracom/sds-mcp-server

Add --scope user to make it available in every project. Check connection with /mcp inside a session.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sds-server": {
      "command": "npx",
      "args": ["-y", "@soracom/sds-mcp-server"]
    }
  }
}

Common uses

Mention sds-server or “SDS MCP” in your prompt if the assistant does not pick the server automatically.

Find the right component

Use sds-server to list SDS form components and recommend which one to use for a required region selector.

Inspect a component

Use sds-server to show the supported modifiers and templates for ds-button.

Generate component HTML

Use sds-server to generate a large primary ds-button with the users icon and the label "Invite users".

Validate existing markup

Use sds-server to validate this SDS HTML and fix the class format:
<button class="ds-button--primary"><span>Save</span></button>

Build a form

Use sds-server to create an SDS form with email, password, region select, terms checkbox, and a "Create account" submit button.

Adapt a template

Use sds-server to get a ds-card template and adapt it for a billing summary card with a heading, amount, status tag, and details link.

Troubleshooting

If the server fails to start in an AI tool, run npx -y @soracom/sds-mcp-server in a terminal first. This separates package authentication problems from MCP client configuration problems.

If npm returns 404 or an authentication error, check that:

@soracom:registry points to https://npm.pkg.github.com.
The GitHub token has read:packages.
The GitHub account has access to the package.

If the client starts the server but no tools appear, restart the client and inspect its MCP server status. Most clients expose this through an MCP settings panel, MCP: List Servers, codex mcp list, claude mcp list, or /mcp.

On Windows, if a client cannot start npx directly, configure the server through cmd:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@soracom/sds-mcp-server"]
}