MCP Server

The Axiom Model Context Protocol (MCP) server enables AI assistants like Claude Code and Cursor to access the Axiom Design System through real-time access to:

Component documentation, props, and usage patterns
Design tokens for colors, spacing, typography, and more
Icon search capabilities
Reference test files showing the repo’s testing conventions
Setup guides and best practices

#
Installation

#
Claude Code

Add the MCP server to your workspace configuration file at .vscode/mcp.json:


{
  "servers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "@optiaxiom/mcp@^1"]
    }
  }
}

#
Cursor

Add to your Cursor MCP configuration:


{
  "mcpServers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "@optiaxiom/mcp@^1"]
    }
  }
}

#
Global installation (optional)

For faster startup times, you can install the package globally:


npm install -g @optiaxiom/mcp@^1


pnpm add -g @optiaxiom/mcp@^1


yarn global add @optiaxiom/mcp@^1


bun add --global @optiaxiom/mcp@^1

Then update your configuration to use the global installation:


{
  "servers": {
    "axiom": {
      "command": "axiom-mcp"
    }
  }
}

#
Available Tools

#
`search_components`

Search Axiom components by name, description, or keywords.

query (string, optional): Search query (component name, keyword, or description). Leave empty to browse all components.
category (string, optional): Filter by category (e.g., “form”, “layout”, “navigation”, “feedback”, “overlay”, “data-display”, “actions”, “typography”)
limit (number, optional): Maximum results to return (default: 5)

Get information about a specific component. Returns the component’s description, import statement, sub-components, and example titles by default. Use the optional props parameter to search for specific props.

name (string, required): Component name (e.g., “Button”, “Dialog”, “Alert”)
props (string, optional): Search query to find specific props by name or description (e.g., “appearance size”, “loading”, “padding background”). Searches both component-specific props and style props. Omit to get just the component overview without any prop definitions.

#
`get_patterns`

Find usage examples showing how Axiom components work together. Returns real working examples from the docs.

components (string, required): Space-separated component names to find patterns for (e.g., “Field Input Button”). Returns examples that use these components together.
query (string, optional): Search within example titles to find specific patterns (e.g., “addon”, “form”, “disabled”).
limit (number, optional): Maximum number of examples to return (default: 5, max: 10)

#
`get_tokens`

Get design token mappings for converting hardcoded values to semantic tokens (e.g., #4F576E → fg.secondary, 32px height → h="md").

categories (string[], optional): Filter to specific token categories. Valid values: borderRadius, boxShadow, colors, duration, fontFamily, fontSize, maxSize, size, zIndex. Returns all categories if omitted.

#
`search_icons`

Search for icons from the @optimizely/axiom-icons package by keyword.

query (string, required): Search query (e.g., “message”, “arrow”, “user”)
limit (number, optional): Maximum results to return (default: 10)

#
`get_tests`

Get vetted reference test files showing the repo’s testing conventions (custom vitest.rtl render helper, role/name queries, accessibility assertions). Use when writing or fixing a spec for an Axiom component.

components (string, optional): Space-separated component names to find reference tests for (e.g., “Alert Button”). Omit to list all available reference tests.
limit (number, optional): Maximum number of reference tests to return when searching by component (default: 5). Ignored when listing all tests.

#
`get_guides`

Get setup, configuration, and integration guides for the Axiom Design System (including this one).

names (string, optional): Space-separated guide names to fetch (e.g., “css-imports css-layers”). Omit to list all available guides.

#
Usage

Once configured, you can ask your AI assistant natural language questions about Axiom:

“Create a form with Input and Button components”
“What props does the Button component accept for styling?”
“Show me how Dialog and DialogForm work together”
“Convert this Figma color #4F576E to an Axiom token”
“Search for message icons”
“What navigation components are available?”