@wix/mcp

Wix MCP

Installation & Usage

From npm Package

npx @wix/mcp

Local Development

• Clone the repository
• Install dependencies
• 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

Enable specific standard tools (all enabled by default):

--tools=WDS,REST,SDK,WIX_HEADLESS,BUILD_APPS,VELO,BUSINESS_SOLUTIONS

Experimental Tools

Enable experimental tools (disabled by default):

--experimental=WIX_API,CLI_COMMAND,GET_TO_KNOW_WIX,VELO_README,WIX_API_THROUGH_FS

CLI Mode

Specify CLI mode:

--cli=wix-one

Logger

Set logging output:

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

Tool Reference

Standard Tools:

• WDS: Wix Design System Documentation (SearchWixWDSDocumentation)
• REST: Wix REST API Documentation (SearchWixRESTDocumentation)
• SDK: Wix SDK Documentation (SearchWixSDKDocumentation)
• BUILD_APPS: Build Apps Documentation (SearchBuildAppsDocumentation)
• WIX_HEADLESS: Wix Headless Documentation (SearchWixHeadlessDocumentation)
• VELO: Velo Documentation (SearchWixVeloDocumentation)
• BUSINESS_SOLUTIONS: Business solutions recipes (WixBusinessFlowsDocumentation)
• CLI: Wix CLI Documentation (SearchWixCLIDocumentation)

Experimental Tools:

• WIX_API: Wix API tools (CallWixSiteAPI) using provided --wixAuthorization token
• CLI_COMMAND: CLI commands for Wix apps (RunWixCliCommand)
• GET_TO_KNOW_WIX: Enables WixREADME and adjusts docs tools to depend on it
• VELO_README: Provides Velo-specific project context (VeloREADME)
• WIX_API_THROUGH_FS: Adds CallWixSiteAPI authenticated via local Wix CLI files

Experimental tools are in early development and may have limited functionality or breaking changes. They must be explicitly enabled with --experimental.

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 20 is required to build.