Skip to Content
MCP Server

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 server to your project with the Claude Code CLI:

claude mcp add --scope project axiom -- npx -y @optiaxiom/mcp@latest

Or add it to .mcp.json at the root of your project yourself:

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

Check .mcp.json into the repository so every contributor and agent working in it gets the server. Claude Code asks each of them to approve it the first time it starts in the project.

The @latest tag in these configurations makes npx check for a new release each time the server starts, so the server’s docs keep up with @optiaxiom/react even when an older copy is installed in the project or globally.

#

Cursor

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

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

#

VS Code

Add to .vscode/mcp.json in your project:

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

#

Global installation (optional)

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

npm install -g @optiaxiom/mcp

Then point your configuration at the global binary (under servers in VS Code):

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

A global install stays on the version you installed, and its docs fall behind each release. Rerun the install to update it.

#

Troubleshooting

If your assistant doesn’t use the Axiom tools, check that the server started: run /mcp in Claude Code, or check the server’s status in Cursor’s settings.

npx downloads the server through the npm registry your project’s .npmrc points to. If that is a private registry that needs a token, the download fails once the token is missing or expired, and the server doesn’t start. Pin the public registry in the server’s arguments:

{ "mcpServers": { "axiom": { "command": "npx", "args": [ "-y", "--registry", "https://registry.npmjs.org", "@optiaxiom/mcp@latest" ] } } }

#

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_component

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 @optiaxiom/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

#

Example prompts

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?”

#

Resources

Last updated on