Crystallize MCP server

Crystallize MCP

MCP server for Crystallize headless commerce. Gives AI agents read and write access to your catalogue, products, shapes, orders, customers, and tenant config — with deep links back to the Crystallize UI, dry-run safety for mutations, and PII masking for customer data.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, Copilot, and any MCP-compatible client.

Getting started

Setup wizard

The interactive wizard handles config, auth tokens, keychain storage, and PII mode in one step:

# Project-level — writes .mcp.json in the current directory (shared with your team)
npx @hayodev/crystallize-mcp --setup

# Global — registers via `claude mcp add` (Claude Code) or writes Claude Desktop config
npx @hayodev/crystallize-mcp --setup --global

Manual config

Standard MCP config (works in any client):

{
  "mcpServers": {
    "crystallize": {
      "command": "npx",
      "args": ["-y", "@hayodev/crystallize-mcp@latest"],
      "env": {
        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant"
      }
    }
  }
}

Add CRYSTALLIZEACCESSTOKENID and CRYSTALLIZEACCESSTOKENSECRET to the env block for PIM tools (shapes, orders, customers). See Authentication.

Claude Code (CLI)

claude mcp add crystallize \
  -e CRYSTALLIZE_TENANT_IDENTIFIER=your-tenant \
  -e CRYSTALLIZE_ACCESS_TOKEN_ID=your-token-id \
  -e CRYSTALLIZE_ACCESS_TOKEN_SECRET=your-token-secret \
  -- npx -y @hayodev/crystallize-mcp@latest

Use --scope project to write to .mcp.json (shared with your team) or --scope user for personal use across all projects.

Claude Desktop

Add the standard config to ~/Library/Application Support/Claude/claudedesktopconfig.json (macOS) or %APPDATA%\Claude\claudedesktopconfig.json (Windows).

Cursor

Add the standard config to your Cursor MCP settings (~/.cursor/mcp.json or the project-level .cursor/mcp.json).

VS Code / GitHub Copilot

Add the standard config to .vscode/mcp.json in your project root.

{
  "servers": {
    "crystallize": {
      "command": "npx",
      "args": ["-y", "@hayodev/crystallize-mcp@latest"],
      "env": {
        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant",
        "CRYSTALLIZE_ACCESS_TOKEN_ID": "your-token-id",
        "CRYSTALLIZE_ACCESS_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Windsurf

Add the standard config to ~/.codeium/windsurf/mcp_config.json.

Gemini CLI

Add the standard config to ~/.gemini/settings.json.

JetBrains AI Assistant

Add the standard config to .junie/mcp.json in your project root.

Warp

Add the standard config to ~/.warp/mcp.json.

Raycast

Open "Install MCP Server" in Raycast and fill in:

• Command: npx
• Arguments: -y @hayodev/crystallize-mcp@latest
• Environment: add CRYSTALLIZETENANTIDENTIFIER and your token vars

Or copy the standard config JSON above before opening the command — Raycast will auto-fill the form.

From source (maintainers)

Shortened. The full README is on GitHub.