Skip to content

MCP Server ​

Axiom includes an MCP (Model Context Protocol) server that brings its Apple-platform development skills to any MCP-compatible AI coding tool — VS Code, Claude Desktop, Cursor, Gemini CLI, OpenCode, and more.

What You Get ​

The MCP server exposes Axiom's full catalog:

  • 289 skills as MCP Resources, loaded on demand, plus tools to browse, search, and read them (axiom_get_catalog, axiom_search_skills, axiom_read_skill)
  • 44 agents, whose instructions your assistant fetches with the axiom_get_agent tool and then follows
  • 18 commands as MCP Prompts (structured workflows)
  • xclog, xcsym, and xcprof as MCP Tools, for console capture, crash symbolication, and CPU profiling on an Apple Silicon Mac with Xcode
  • xcproject, for inspecting Xcode projects. It has no MCP tool, so your assistant runs it in a shell as npx -y -p axiom-mcp xcproject
  • Apple's documentation bundled inside Xcode, searchable alongside Axiom's skills when Xcode is installed

Two of Axiom's tools aren't available over MCP. Without axbuild, your assistant saves build and test output to a log file and reads it. Without xcui, it can still send simulator input through AXe if you've installed it, but has no equivalent for xcui's waits, assertions, accessibility settings, system dialogs, VoiceOver checks or resize sweeps.

Prerequisites ​

  • Node.js 18+ – check with node --version

That's it. No cloning, no building.

Installation by Tool ​

Each tool needs a configuration snippet that tells it how to launch the Axiom MCP server.

VS Code ​

Add this to ~/.copilot/mcp-config.json to use Axiom in every project, or to .mcp.json at the root of a project for just that one:

json
{
  "mcpServers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "axiom-mcp"]
    }
  }
}

MCP: Add Server in the Command Palette walks you through the same setup. VS Code still reads the older .vscode/mcp.json and user-profile mcp.json files, which use a top-level servers object, but marks them deprecated.

Claude Desktop ​

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

json
{
  "mcpServers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "axiom-mcp"]
    }
  }
}

Cursor ​

When Axiom is installed as a native Cursor plugin, Cursor automatically discovers the plugin-root mcp.json. Do not also add Axiom to .cursor/mcp.json: duplicate definitions can produce duplicate servers or unclear configuration ownership. See the native Cursor install guide.

For an MCP-only setup without the native plugin, add this exact configuration to .cursor/mcp.json in your workspace:

json
{
  "mcpServers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "axiom-mcp"]
    }
  }
}

Gemini CLI ​

Add to ~/.gemini/settings.json (or .gemini/settings.json in a project):

json
{
  "mcpServers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "axiom-mcp"]
    }
  }
}

OpenCode ​

Add to opencode.jsonc in your project root (or ~/.config/opencode/opencode.jsonc for global):

json
{
  "mcp": {
    "axiom": {
      "type": "local",
      "command": ["npx", "-y", "axiom-mcp"]
    }
  }
}

Or use the CLI: opencode mcp add and follow the prompts.

Configuration ​

Environment Variables ​

VariableValuesDefaultDescription
AXIOM_MCP_MODEdevelopment, productionproductionRuntime mode
AXIOM_DEV_PATHFile path—Plugin directory for development mode
AXIOM_LOG_LEVELdebug, info, warn, errorinfoLogging verbosity
AXIOM_APPLE_DOCSfalseEnabledSet to false to leave Xcode's bundled Apple documentation out of the catalog
AXIOM_XCODE_PATHPath to an Xcode appThe one xcode-select points toThe Xcode whose bundled documentation and version the server reads
AXIOM_XCLOG_PATH, AXIOM_XCSYM_PATH, AXIOM_XCPROF_PATHFile pathBundled binaryUse a different xclog, xcsym, or xcprof binary
AXIOM_XCLOG_TIMEOUT, AXIOM_XCSYM_TIMEOUT, AXIOM_XCPROF_TIMEOUTSeconds120, 120, 300Time limit for each call to that tool; raise it for long recordings
AXIOM_FULL_READ_LIMITCharacters20000Size above which axiom_read_skill returns a skill's section list instead of its full text, unless the call names sections or passes full: true, or the skill has one section

Development Mode (Live Skills) ​

For Axiom contributors working on skills:

bash
AXIOM_MCP_MODE=development \
AXIOM_DEV_PATH=/path/to/Axiom/.claude-plugin/plugins/axiom \
node /path/to/Axiom/axiom-mcp/dist/index.js

Changes to skill files are reflected immediately — no rebuild needed.

Production Mode (Bundled) ​

The default when you install from npm. The server reads Axiom's skills from a pre-compiled snapshot instead of a plugin checkout.

bash
npx axiom-mcp

Verify It Works ​

Quick Test ​

Run the server directly to confirm it launches without errors:

bash
npx axiom-mcp

The server should start and wait for stdin input (MCP uses stdio transport). Press Ctrl+C to stop.

MCP Inspector ​

For interactive testing, use the official MCP Inspector:

bash
npx @modelcontextprotocol/inspector npx axiom-mcp

This opens a web UI where you can browse resources, test prompts, and invoke tools.

In Your Tool ​

Once it's configured, try asking your assistant:

"What Axiom skills do you have for debugging iOS builds?"

It should list Axiom's skills from the MCP server.

Troubleshooting ​

Server Won't Start ​

Check that Node.js is version 18 or newer:

bash
node --version

Skills Not Appearing ​

Turn on debug logging to see what the server loads:

bash
AXIOM_LOG_LEVEL=debug npx axiom-mcp 2>&1 | grep -i skill

Client Can't Connect ​

MCP communicates over stdin and stdout. Common issues:

  • Wrong config – Make sure command is "npx" and args is ["-y", "axiom-mcp"]
  • Other stdout writers – Make sure nothing else writes to stdout; the server logs only to stderr

Run the command from your config by hand:

bash
npx axiom-mcp
# Should start without errors, waiting for stdin

What's Next ​

Released under the MIT License