Wix MCP

Installation & Usage

From npm Package

npx @wix/mcp

Authentication

Two ways to authenticate:

--wixCliAuth — recommended. Run npx @wix/cli login once; it writes an OAuth token to ~/.wix/auth/account.json. The access token is then refreshed for you when it nears expiry. If the file is missing, the server exits with an error telling you to log in first.

--wixAuthorization / --wixApiKeyFile See Authentication via an API key.

With no auth flag, @wix/mcp serves documentation and onboarding tools only — search and read Wix docs, without management tools.

Claude Code

claude mcp add wix -- npx -y @wix/mcp --wixCliAuth

Codex

codex mcp add wix -- npx -y @wix/mcp --wixCliAuth

Cursor

Cursor doesn't expose a CLI for managing MCP servers — use Settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json (global) / <project>/.cursor/mcp.json (per-project):

{
  "mcpServers": {
    "wix": {
      "command": "npx",
      "args": ["-y", "@wix/mcp", "--wixCliAuth"]
    }
  }
}

Other clients (Claude Desktop, VS Code, etc.)

For any client without an mcp add CLI, drop this into its MCP config:

{
  "mcpServers": {
    "wix": {
      "command": "npx",
      "args": ["-y", "@wix/mcp", "--wixCliAuth"]
    }
  }
}

Local Development

1. Clone the repository
2. Install dependencies
3. Build the project

Run locally with:

npx /Users/absolute/path/to/repo/dir/.

Or directly with Node:

node /Users/absolute/path/to/build/bin-standalone.js

Configuration Options

Tool Selection

By default the server serves the same tools as the hosted Wix MCP at https://mcp.wix.com/mcp, apart from a few that only work there. The Tool Reference lists every tool it serves.

--tools chooses which documentation search tools are served, by category. It replaces the default (every category except VELO):

--tools=WDS,REST,SDK,WIX_HEADLESS,BUILD_APPS,VELO,CLI,OVERVIEW,HELP_CENTER

--enableTools turns tools on by name:

--enableTools=ListWixSites

--disableTools turns tools off by name:

--disableTools=ReportIssueToWix,ExecuteWixAPI

A tool named in both --enableTools and --disableTools is served.

A flag with no value exits with an error. A tool name that isn't served is ignored.

Experimental Tools

Enable experimental tools (disabled by default):

--experimental=CLI_COMMAND,VELO_README

Authentication via an API key

Pass a key directly:

--wixAuthorization=<key>

Or read the one already on this machine:

--wixApiKeyFile

--wixApiKeyFile reads ~/.wix/auth/api-key.json, the API key file the Wix CLI writes. This is the older API-key flow, kept for backward compatibility; --wixCliAuth is the better choice for new setups.

Get To Know Wix

WixREADME is on by default. Turn it off with:

--getToKnowWix=false

CLI Mode

Targets RunWixCliCommand at the Wix One CLI instead of the default Wix CLI. Only has an effect together with --experimental=CLI_COMMAND:

--cli=wix-one

Logger

Set logging output:

• --logger=mcp (default, sends logs to your MCP client)
• --logger=file (logs to ~/wix-mcp-log.txt)

Tool Reference

Tool names for --enableTools and --disableTools.

Always served:

• Docs search — the tool name, and the --tools category that selects it:

| --tools | Tool | | --- | --- | | REST | SearchWixRESTDocumentation | | SDK | SearchWixSDKDocumentation | | WDS | SearchWixWDSDocumentation | | BUILD_APPS | SearchBuildAppsDocumentation | | WIX_HEADLESS | SearchWixHeadlessDocumentation | | CLI | SearchWixCLIDocumentation | | OVERVIEW | SearchDevelopmentDocumentation | | HELP_CENTER | SearchWixHelpCenter | | VELO (not in the default) | SearchWixVeloDocumentation |

• Docs reading: BrowseWixRESTDocsMenu, ReadFullDocsArticle, ReadFullDocsMethodSchema
• Getting started: WixREADME, StartDeployWebsite, StartHeadlessBuild
• Domains: CheckDomainAvailability

Added by any auth flag:

• Wix APIs: CallWixSiteAPI, ListWixSites, ManageWixSite, UploadImageToWixSite
• Running code against the APIs: SearchWixAPISpec, ExecuteWixAPI
• Site creation: UploadHeadlessWebsiteFiles, WixHarmonyEditorBuild, pullSiteCreationJob, GetSuggestedDomains, SearchSiteTemplates, CreateSiteFromTemplate
• Other: ReportIssueToWix, GetSiteContext

Added by --experimental:

• CLI_COMMAND → RunWixCliCommand: run Wix CLI commands for Wix apps
• VELO_README → VeloREADME: Velo-specific project context

Experimental tools are in early development and may have limited functionality or breaking changes.

Toolkit API (Programmatic Usage)

The Toolkit API lets you use @wix/mcp tools in-process without running an MCP server. This is the recommended approach for AI agent integrations (Vercel AI SDK, LangChain, custom agent loops, etc.).

Quick Start

import { createWixToolkit, extractText } from '@wix/mcp';

const toolkit = createWixToolkit({
  auth: {
    siteToken: async (siteId) => ({ Authorization: `Bearer ${myToken}` }),
    accountToken: async () => ({ Authorization: `Bearer ${myToken}` }),
  },
  docs: { tools: ['REST'], getToKnowWixEnabled: true },
  api: { tools: ['CallWixSiteAPI'] },
  defaults: { siteId: 'my-site-id' },
  clientName: 'my-app',
});

// Get all tools as plain objects
for (const tool of toolkit.getTools()) {
  console.log(tool.name, tool.description);
  console.log(tool.inputSchema);  // Zod schema
}

// Execute a tool
const result = await toolkit.getTool('SearchWixRESTDocumentation')!
  .execute({ searchTerm: 'query products', reason: 'find endpoint' });
console.log(extractText(result));

// Pre-load WixREADME content for system prompt injection
const readme = await toolkit.preloadReadme();

createWixToolkit(options)

Returns a WixToolkit with the following methods:

| Method | Returns | Description | |--------|---------|-------------| | getTools() | WixTool[] | All registered tools | | getTool(name) | WixTool \| undefined | Look up a tool by name | | getToolNames() | string[] | List of tool names | | preloadReadme() | Promise<string \| null> | Pre-load WixREADME content |

Options

| Option | Type | Description | |--------|------|-------------| | auth | WixToolkitAuth | Required. Auth headers for API calls. Either { siteToken, accountToken } functions or a full McpAuthenticationStrategy. | | docs | WixToolkitDocsConfig | Docs tools config. tools selects sources ('REST', 'SDK', etc.). getToKnowWixEnabled: true enables WixREADME. | | api | WixToolkitApiConfig | API tools config. tools selects which API tools to register ('CallWixSiteAPI', 'ListWixSites', 'ManageWixSite'). | | defaults | Record<string, any> | Values to hide from tool schemas and auto-inject at execute time. Commonly used for siteId. | | exclude | string[] | Tool names to filter out after registration. | | clientName | string | Consumer identifier for BI tracking. | | hooks | WixToolkitHooks | Lifecycle callbacks for observability (see below). |

WixTool Interface

Each tool returned by getTools() has:

interface WixTool {
  name: string;                              // e.g. 'CallWixSiteAPI'
  description: string;                       // LLM-facing description
  inputSchema: z.ZodObject<any>;             // Zod schema for parameters
  annotations?: ToolAnnotations;             // MCP annotations (readOnlyHint, etc.)
  execute(args: Record<string, any>): Promise<CallToolResult>;
}

defaults — Hiding and Injecting Parameters

Use defaults to remove fields from tool schemas and auto-inject values at execute time. This is how you handle parameters the LLM shouldn't control (e.g., siteId):

const toolkit = createWixToolkit({
  auth: { ... },
  api: { tools: ['CallWixSiteAPI'] },
  defaults: { siteId: 'my-site-id' },
});

// CallWixSiteAPI schema no longer has siteId — the LLM won't see it
// When execute() is called, siteId is automatically merged into args
const tool = toolkit.getTool('CallWixSiteAPI')!;
await tool.execute({ url: 'https://...', method: 'GET', reason: '...' });
// internally calls the API with { siteId: 'my-site-id', url: '...', method: 'GET', ... }

Lifecycle Hooks

const toolkit = createWixToolkit({
  // ...
  hooks: {
    beforeExecute: (toolName, args) => {
      console.log(`[${toolName}] starting`, args);
    },
    afterExecute: (toolName, result, durationMs) => {
      console.log(`[${toolName}] done in ${durationMs}ms`, result.isError ? 'ERROR' : 'OK');
    },
    onError: (toolName, error, durationMs) => {
      console.error(`[${toolName}] threw after ${durationMs}ms`, error);
    },
  },
});

Hooks are separate from the library's internal Panorama/BI telemetry, which runs automatically.

extractText(result)

Helper to extract text content from a CallToolResult:

import { extractText } from '@wix/mcp';

const result = await tool.execute({ searchTerm: 'products' });
const text = extractText(result);  // concatenated text blocks, non-text filtered out

Vercel AI SDK Integration Example

import { createWixToolkit, extractText } from '@wix/mcp';
import { tool } from 'ai';
import { zodToJsonSchema } from 'zod-to-json-schema';

const toolkit = createWixToolkit({ auth: { ... }, docs: { tools: ['REST'] } });

// Convert WixTools to Vercel AI SDK tools
const aiTools = Object.fromEntries(
  toolkit.getTools().map(t => [
    t.name,
    tool({
      description: t.description,
      parameters: t.inputSchema,
      execute: async (args) => extractText(await t.execute(args)),
    }),
  ])
);

Resources

The resource feature provides access to Wix documentation via the MCP server:

• Fetches documentation indexes from specified Wix portals
• Makes documentation articles available as resources
• Allows fetching article content using the MCP protocol

Resources use the wix-docs:// URI scheme, which maps to Wix Docs URLs:

• Docs URL: https://dev.wix.com/docs/...
• Resource URI: wix-docs://...

To load all docs from a portal:

--portals=<docs-portal-name>

Cursor Integration

MCP Docs

See: https://docs.cursor.com/context/model-context-protocol

Configuration (~/.cursor/mcp.json)

Using npm package

{
  "mcpServers": {
    "wix-local-mcp": {
      "command": "npx",
      "args": ["-y", "@wix/mcp"]
    }
  }
}

Using local build

{
  "mcpServers": {
    "wix-local-mcp": {
      "command": "npx",
      "args": ["/Users/absolute/path/to/repo/dir/."]
    }
  }
}

Using Node

{
  "mcpServers": {
    "wix-local-mcp": {
      "command": "node",
      "args": ["/Users/absolute/path/to/build/bin-standalone.js"]
    }
  }
}

BI Events

MCP usage analytics and BI events can be viewed in the BI catalog:

• MCP BI Events (Event 39:1607)

Troubleshooting

• Check logs from Claude Desktop or Cursor
• For Node/fnm/nvm errors: ensure the latest Node version is set as default
• For npx errors: use -y and the correct npm registry
• Try specifying the full path to Node
• Try using Bun and index.ts directly
• Ensure build files have appropriate permissions

NVM Example Fix

"wix-mcp-remote-prod": {
  "command": "npx",
  "args": ["-y", "@wix/mcp-remote", "https://mcp.wix.com/sse"],
  "env": {
    "PATH": "<path-to-your-nvm-node-version>/bin"
  }
}

FNM Example Fix

{
  "mcpServers": {
    "wix-mcp-remote-prod": {
      "command": "sh",
      "args": [
        "-c",
        "eval $(fnm env) && npx -y @wix/mcp-remote https://mcp.wix.com/sse"
      ]
    }
  }
}

Node 24 is required to build.