MainWP MCP Server - MainWP Documentation

The MainWP MCP Server is in beta. APIs and configuration options may change between versions.

Download from GitHub

Get the MainWP MCP Server source code, installation instructions, and latest releases.

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external data sources and tools. Instead of copying data into prompts or building one-off integrations, MCP gives AI tools a consistent way to discover and execute capabilities. The MainWP MCP Server implements MCP for MainWP Dashboard. It exposes MainWP Abilities API operations as MCP tools so AI assistants like Claude, Cursor, OpenAI Codex, and VS Code Copilot can manage your WordPress network through natural language. When you ask “What sites need updates?” or “Sync all my sites,” the AI assistant calls the appropriate MainWP ability through the MCP server, which talks to your Dashboard through the Abilities API.

What You Can Do

Manage sites, including listing, syncing, reconnecting, adding, and removing child sites
Review and apply WordPress, plugin, theme, and translation updates
Inspect and manage installed plugins and themes
Work with clients, site assignments, and cost data
Run bulk operations across many child sites

What You’ll Learn

How to install and configure the MainWP MCP Server
How to connect Claude, VS Code Copilot, Cursor, OpenAI Codex, and other MCP clients
Available safety controls and configuration options
Troubleshooting connection issues

Prerequisites

Node.js 20.19.0 or later
MainWP Dashboard 6.0 or later
A WordPress user with the capabilities required for the actions you want to run
A supported authentication method for that user. The examples below use a WordPress Application Password, and upstream troubleshooting also documents bearer-token authentication via MAINWP_TOKEN.

Quick Start

Option A: Run with `npx` (Recommended)

Run the server directly:

npx -y @mainwp/mcp

Credentials are loaded from ./settings.json or ~/.config/mainwp-mcp/settings.json.

Option B: Clone and build (Development)

Clone and build the MCP server locally:

git clone https://github.com/mainwp/mainwp-mcp.git
cd mainwp-mcp
npm ci
npm run build

Then:

Create an Application Password.
Configure your AI tool.
Ask “What sites need updates?” or “Sync all my sites.”

Create an Application Password

The recommended authentication method is a WordPress Application Password. It is separate from your login password and can be revoked independently.

The MainWP MCP Server also supports bearer-token authentication via MAINWP_TOKEN. This page uses Application Password examples because that is the primary setup flow documented here.

Open your WordPress profile

In your MainWP Dashboard, click your username in the top-right corner and open Users > Profile in WordPress admin.

Find the Application Passwords section

Scroll to the Application Passwords section near the bottom of the profile page.

Create a password

Enter a label such as MainWP MCP Server and click Add New Application Password.

Copy the generated password

Save the generated password immediately. WordPress only shows it once.

WordPress displays the password with spaces for readability. You can use it with or without the spaces.

Use a dedicated WordPress user for MCP access when possible. It is easier to audit and revoke later.

For more background, see Application Passwords.

Credential Configuration

You can provide credentials in two ways. Both approaches are supported.

Option A: Per-Tool Configuration (Recommended)

Store credentials directly in the MCP config for each AI tool. This is the standard MCP pattern and lets you use separate Application Passwords per tool.

{
  "mcpServers": {
    "mainwp": {
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "env": {
        "MAINWP_URL": "https://your-dashboard.com",
        "MAINWP_USER": "admin",
        "MAINWP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Option B: Centralized Settings File

Store credentials once in ~/.config/mainwp-mcp/settings.json:

{
  "dashboardUrl": "https://your-dashboard.com",
  "username": "admin",
  "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx"
}

Set restrictive permissions on the file:

chmod 600 ~/.config/mainwp-mcp/settings.json

This works well when you use several AI tools or want to rotate credentials in one place. If you manage multiple dashboards, create a separate folder for each one with its own settings.json, then point the MCP client at the correct directory with cwd:

{
  "mcpServers": {
    "mainwp-staging": {
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "cwd": "/path/to/dashboard-credentials"
    }
  }
}

The server checks ./settings.json first, then ~/.config/mainwp-mcp/settings.json. Environment variables in per-tool configuration override settings file values. Use per-tool configuration unless you have a clear reason not to. It is the standard MCP pattern and makes it easier to isolate credentials by client.

Neither approach uses true system environment variables. For higher-isolation credential workflows, see the security guide in Related Resources.

Installation

Claude Code

Add the MCP server using the CLI:

claude mcp add --transport stdio mainwp \
  --env MAINWP_URL=https://your-dashboard.com \
  --env MAINWP_USER=admin \
  --env MAINWP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
  -- npx -y @mainwp/mcp

If you use ~/.config/mainwp-mcp/settings.json, you can omit the --env flags:

claude mcp add --transport stdio mainwp -- npx -y @mainwp/mcp

You can also define the same server in ~/.claude.json.

Claude Desktop

Edit the configuration file at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mainwp": {
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "env": {
        "MAINWP_URL": "https://your-dashboard.com",
        "MAINWP_USER": "admin",
        "MAINWP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

If you already use ~/.config/mainwp-mcp/settings.json, omit the env block.

VS Code (Copilot Agent Mode)

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

{
  "servers": {
    "mainwp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "env": {
        "MAINWP_URL": "https://your-dashboard.com",
        "MAINWP_USER": "admin",
        "MAINWP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

VS Code can also prompt for the Application Password at runtime so it is not stored in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mainwp_password",
      "description": "MainWP Application Password",
      "password": true
    }
  ],
  "servers": {
    "mainwp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "env": {
        "MAINWP_URL": "https://your-dashboard.com",
        "MAINWP_USER": "admin",
        "MAINWP_APP_PASSWORD": "${input:mainwp_password}"
      }
    }
  }
}

If you use the centralized settings file, omit the env block.

Cursor

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "mainwp": {
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "env": {
        "MAINWP_URL": "https://your-dashboard.com",
        "MAINWP_USER": "admin",
        "MAINWP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Cursor also supports ${env:VAR_NAME} placeholders if you want to reference system environment variables. If you use ~/.config/mainwp-mcp/settings.json, omit the env block.

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.mainwp]
command = "npx"
args = ["-y", "@mainwp/mcp"]

[mcp_servers.mainwp.env]
MAINWP_URL = "https://your-dashboard.com"
MAINWP_USER = "admin"
MAINWP_APP_PASSWORD = "xxxx xxxx xxxx xxxx xxxx xxxx"

If you use ~/.config/mainwp-mcp/settings.json, omit the [mcp_servers.mainwp.env] section.

ZenCoder

In VS Code, add the server under zencoder.mcpServers in settings.json:

{
  "zencoder.mcpServers": {
    "mainwp": {
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "env": {
        "MAINWP_URL": "https://your-dashboard.com",
        "MAINWP_USER": "admin",
        "MAINWP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

In JetBrains, go to Settings > Tools > Zencoder > MCP Servers and use the same JSON structure. If you use ~/.config/mainwp-mcp/settings.json, omit the env block.

Other MCP Clients

Windsurf and most other MCP hosts use the same JSON pattern shown above:

command: npx
args: ["-y", "@mainwp/mcp"]
env: MAINWP_URL, MAINWP_USER, and MAINWP_APP_PASSWORD

Available Tools

The MCP server currently exposes 64 tools. Tool names omit the mainwp/ namespace and replace hyphens with underscores. For example, mainwp/list-sites-v1 becomes list_sites_v1. Use the category pages below for the current ability list, parameters, and response schemas.

Sites

Manage child sites, plugins, themes, sync operations, and related site data.

Updates

Review and apply WordPress, plugin, theme, and translation updates.

Clients

Create and manage client records, assignments, and related metadata.

Batch Operations

Check the status of queued large-scale operations.

MCP Resources

The server also exposes inspection resources:

URI	Description
`mainwp://abilities`	Full list of available abilities with schemas
`mainwp://categories`	List of ability categories
`mainwp://status`	Current connection status
`mainwp://help`	Tool documentation and safety conventions

Configuration Reference

Environment Variables

Variable	Required	Default	Description
`MAINWP_URL`	Yes	-	Base URL of your MainWP Dashboard
`MAINWP_USER`	Yes	-	WordPress admin username
`MAINWP_APP_PASSWORD`	Yes	-	WordPress Application Password
`MAINWP_SKIP_SSL_VERIFY`	No	`false`	Skip SSL verification for development only
`MAINWP_ALLOW_HTTP`	No	`false`	Allow HTTP URLs
`MAINWP_SAFE_MODE`	No	`false`	Block destructive operations
`MAINWP_REQUIRE_USER_CONFIRMATION`	No	`true`	Require preview and explicit approval for destructive actions
`MAINWP_ALLOWED_TOOLS`	No	-	Comma-separated allowlist of exposed tools
`MAINWP_BLOCKED_TOOLS`	No	-	Comma-separated blocklist of hidden tools
`MAINWP_SCHEMA_VERBOSITY`	No	`standard`	`standard` or `compact`
`MAINWP_RATE_LIMIT`	No	`60`	Maximum API requests per minute
`MAINWP_REQUEST_TIMEOUT`	No	`30000`	Request timeout in milliseconds
`MAINWP_MAX_RESPONSE_SIZE`	No	`10485760`	Maximum response size in bytes (10MB)
`MAINWP_MAX_SESSION_DATA`	No	`52428800`	Maximum cumulative session data in bytes (50MB)
`MAINWP_RETRY_ENABLED`	No	`true`	Enable automatic retry for transient errors
`MAINWP_MAX_RETRIES`	No	`2`	Total retry attempts including the initial request
`MAINWP_RETRY_BASE_DELAY`	No	`1000`	Base delay between retries in milliseconds
`MAINWP_RETRY_MAX_DELAY`	No	`2000`	Maximum delay between retries in milliseconds

`settings.json`

Instead of environment variables, you can use a settings.json file:

{
  "dashboardUrl": "https://your-dashboard.com",
  "username": "admin",
  "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx",
  "rateLimit": 60,
  "requestTimeout": 30000,
  "maxResponseSize": 10485760,
  "maxSessionData": 52428800,
  "retryEnabled": true,
  "maxRetries": 2,
  "retryBaseDelay": 1000,
  "retryMaxDelay": 2000
}

Configuration loads from ./settings.json or ~/.config/mainwp-mcp/settings.json, in that order. Environment variables override file settings. In settings.json, use camelCase keys such as allowedTools, blockedTools, safeMode, schemaVerbosity, rateLimit, requestTimeout, maxResponseSize, and maxSessionData.

Only enable MAINWP_SKIP_SSL_VERIFY or MAINWP_ALLOW_HTTP for local development or isolated test environments. Do not use them in production or on untrusted networks.

Optimize Token Usage

The server exposes 64 tools, which take roughly 28,000 tokens in an AI client’s context window. If you want a smaller MCP surface area, use compact schemas and tool filtering.

Compact Schema Mode

Reduce tool description size with:

{
  "schemaVerbosity": "compact"
}

Or with an environment variable:

MAINWP_SCHEMA_VERBOSITY=compact

Compact mode truncates descriptions to 60 characters and removes examples. It also relies more heavily on MCP semantic annotations instead of inline safety text.

Limit Exposed Tools

For focused automation, combine compact schemas with an allowlist:

{
  "schemaVerbosity": "compact",
  "allowedTools": ["list_sites_v1", "get_site_v1", "list_updates_v1", "run_updates_v1"]
}

To hide destructive tools while keeping everything else available:

{
  "blockedTools": [
    "delete_site_v1",
    "delete_client_v1",
    "delete_tag_v1",
    "delete_site_plugins_v1",
    "delete_site_themes_v1"
  ]
}

Safety Features

Two-Step Confirmation

Destructive operations require explicit confirmation. The MCP server first returns a preview, then waits for user approval before execution. Previews expire after 5 minutes. This confirmation flow applies to:

delete_site_v1
delete_client_v1
delete_tag_v1
delete_site_plugins_v1
delete_site_themes_v1

For unattended automation, disable the confirmation flow:

{
  "requireUserConfirmation": false
}

Or with an environment variable:

MAINWP_REQUIRE_USER_CONFIRMATION=false

Safe Mode

Enable safe mode to block destructive operations entirely:

{
  "safeMode": true
}

Or with an environment variable:

MAINWP_SAFE_MODE=true

Troubleshooting

Verify the Connection

Test that your Dashboard REST API is reachable:

curl -I https://your-dashboard.com/wp-json/

Test authentication:

curl -u "username:app-password" \
  https://your-dashboard.com/wp-json/wp/v2/users/me

Test Abilities API access:

curl -u "username:app-password" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities?per_page=1"

If this request fails, verify that the MainWP Abilities API plugin is installed and activated.

Common Errors

401 Unauthorized

Verify that the username matches exactly.
Regenerate the Application Password and update the client configuration.
Check whether a security plugin disables Application Passwords.
If you use two-factor authentication, test whether a 2FA plugin is interfering.

403 Forbidden

Make sure the WordPress user has the capabilities required for the requested operation.

Bearer token not working

Verify that the token was generated correctly in MainWP Dashboard.
Check whether the token has expired.
Use MAINWP_TOKEN for bearer-token authentication, not MAINWP_APP_PASSWORD.
If needed, switch back to Application Password authentication to isolate the issue.

Tool not found

Check the tool name for typos.
Tool names use underscores such as list_sites_v1, not hyphens.
Review allowedTools and blockedTools if the tool is unexpectedly hidden.
Confirm that the underlying ability exists in MainWP Dashboard.

SAFE_MODE_BLOCKED

Safe mode is blocking a destructive operation.
Disable safe mode only if you need destructive operations.

{
  "safeMode": false
}

Confirmation required

Destructive tools use a two-step confirmation flow.
First request a preview, then confirm execution.
If the client is not following that flow, be explicit: ask it to show the preview first.
Check whether requireUserConfirmation is enabled.

For unattended automation:

{
  "requireUserConfirmation": false
}

PREVIEW_REQUIRED

The client tried to execute a destructive action without requesting a preview first.
Request a preview before confirming the action.

PREVIEW_EXPIRED

Previews expire after 5 minutes.
Request a new preview before confirming.

CONFLICTING_PARAMETERS

Do not send user_confirmed: true and dry_run: true together.
Use one or the other depending on whether you want execution or a preview.

INVALID_PARAMETER: user_confirmed not supported

user_confirmed only applies to destructive tools.
Do not send it for non-destructive actions.

SSL certificate problem

Fix the certificate for production use.
For local self-signed development only, set MAINWP_SKIP_SSL_VERIFY=true.

HTTP blocked

The server blocks plain HTTP by default because credentials would be sent unencrypted.
For local development without SSL only, set MAINWP_ALLOW_HTTP=true.

ECONNREFUSED or ETIMEDOUT

Confirm that the dashboard URL is correct and reachable from the machine running the MCP client.
Check firewall, VPN, proxy, and DNS issues.

RESOURCE_EXHAUSTED: Session data limit exceeded

Restart the MCP server to reset the cumulative session counter.
Increase maxSessionData if needed.
Use pagination or narrower filters to reduce response volume.

{
  "maxSessionData": 104857600
}

Response too large

Increase maxResponseSize or reduce the response size with filters such as status filters or lower per_page values.

{
  "maxResponseSize": 20971520
}

Rate limit exceeded

Wait and retry, or increase rateLimit.
Setting rateLimit to 0 disables rate limiting and is not recommended for production.

{
  "rateLimit": 120
}

Configuration file not found

The server checks ./settings.json first, then ~/.config/mainwp-mcp/settings.json.
Validate the file content if the server falls back to defaults.

cat settings.json | jq .

Environment variables not working

Export variables before starting the MCP host.
Variable names are case-sensitive.
Avoid wrapping values in extra nested quotes.

export MAINWP_URL="https://your-dashboard.com"

MCP host not finding the server

Validate the host config file syntax.
Restart the MCP host after config changes.
In VS Code, make sure you are in a workspace and Agent Mode is enabled.

Debugging

Enable verbose logging

node dist/index.js 2>&1 | tee server.log

Check server health directly

MAINWP_URL="https://your-dashboard.com" \
MAINWP_USER="admin" \
MAINWP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
node dist/index.js

The server should write startup messages to stderr and then wait for MCP commands on stdin.

Debug with MCP Inspector

If you cloned the repository locally, you can run the inspector:

npm run inspect

Self-Check Checklist

Verify your MCP Server installation is complete:

You chose an installation method: npx -y @mainwp/mcp or clone and build
A supported authentication method is configured and saved securely
Client configuration created in the correct location for your AI tool
Dashboard URL and the required authentication values added to configuration
If you use centralized credentials, settings.json exists in the expected location
AI tool restarted or reloaded to pick up the new configuration
Test prompt “List all my sites” returns your sites

Abilities API Overview - How abilities work
Sites Abilities - Site management reference
Updates Abilities - Update management reference
Clients Abilities - Client management reference
Tags Abilities - Tag management reference
Batch Operations - Queued job status reference
GitHub Repository - Source code and issues
Configuration Reference - Repository configuration details
Security Guide - Credential and trust-model guidance
Example Prompts - Sample prompts for common workflows
Troubleshooting - Repository troubleshooting reference

Getting Started

Understanding MainWP

Dashboard

Sites

Users

Updates

Plugins

Themes

Content Operations

Clients

API Reference

Troubleshooting

Customization

Advanced

Resources

Download from GitHub

​What You Can Do

​What You’ll Learn

​Prerequisites

​Quick Start

​Option A: Run with npx (Recommended)

​Option B: Clone and build (Development)

​Create an Application Password

​Credential Configuration

​Option A: Per-Tool Configuration (Recommended)

​Option B: Centralized Settings File

​Installation

​Claude Code

​Claude Desktop

​VS Code (Copilot Agent Mode)

​Cursor

​OpenAI Codex

​ZenCoder

​Other MCP Clients

​Available Tools

Sites

Updates

Clients

Tags

Batch Operations

​MCP Resources

​Configuration Reference

​Environment Variables

​settings.json

​Optimize Token Usage

​Compact Schema Mode

​Limit Exposed Tools

​Safety Features

​Two-Step Confirmation

​Safe Mode

​Troubleshooting

​Verify the Connection

​Common Errors

​Debugging

​Debug with MCP Inspector

​Self-Check Checklist

​Related Resources

What You Can Do

What You’ll Learn

Prerequisites

Quick Start

Option A: Run with `npx` (Recommended)

Option B: Clone and build (Development)

Create an Application Password

Credential Configuration

Option A: Per-Tool Configuration (Recommended)

Option B: Centralized Settings File

Installation

Claude Code

Claude Desktop

VS Code (Copilot Agent Mode)

Cursor

OpenAI Codex

ZenCoder

Other MCP Clients

Available Tools

MCP Resources

Configuration Reference

Environment Variables

`settings.json`

Optimize Token Usage

Compact Schema Mode

Limit Exposed Tools

Safety Features

Two-Step Confirmation

Safe Mode

Troubleshooting

Verify the Connection

Common Errors

Debugging

Debug with MCP Inspector

Self-Check Checklist

Related Resources