> ## Documentation Index > Fetch the complete documentation index at: https://docs.mainwp.com/llms.txt > Use this file to discover all available pages before exploring further. # MainWP MCP Server > Connect Claude, Cursor, OpenAI Codex, VS Code Copilot, and other MCP clients to your MainWP Dashboard. The MainWP MCP Server is in beta. APIs and configuration options may change between versions. 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](/api-reference/abilities-api/overview). ## 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: ```bash theme={null} 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: ```bash theme={null} git clone https://github.com/mainwp/mainwp-mcp.git cd mainwp-mcp npm ci npm run build ``` Then: 1. Create an Application Password. 2. Configure your AI tool. 3. 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. In your MainWP Dashboard, click your username in the top-right corner and open **Users > Profile** in WordPress admin. Scroll to the **Application Passwords** section near the bottom of the profile page. Enter a label such as **MainWP MCP Server** and click **Add New Application 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](/api-reference/rest-api/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. ```json theme={null} { "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" } } } } ``` For bearer-token authentication, use `MAINWP_TOKEN` instead of `MAINWP_USER` and `MAINWP_APP_PASSWORD`. ### Option B: Centralized Settings File Store credentials once in `~/.config/mainwp-mcp/settings.json`: ```json theme={null} { "dashboardUrl": "https://your-dashboard.com", "username": "admin", "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx" } ``` Set restrictive permissions on the file: ```bash theme={null} 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`: ```json theme={null} { "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](#related-resources). *** ## Installation ### Claude Code Add the MCP server using the CLI: ```bash theme={null} 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: ```bash theme={null} 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` ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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`: ```toml theme={null} [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`: ```json theme={null} { "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. Manage child sites, plugins, themes, sync operations, and related site data. Review and apply WordPress, plugin, theme, and translation updates. Create and manage client records, assignments, and related metadata. Organize sites and clients with tags. 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` | Conditional | - | WordPress admin username for Application Password authentication | | `MAINWP_APP_PASSWORD` | Conditional | - | WordPress Application Password for Application Password authentication | | `MAINWP_TOKEN` | Conditional | - | MainWP REST API bearer token as an alternative to `MAINWP_USER` and `MAINWP_APP_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: ```json theme={null} { "dashboardUrl": "https://your-dashboard.com", "username": "admin", "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx", "responseFormat": "compact", "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 `apiToken`, `allowedTools`, `blockedTools`, `safeMode`, `schemaVerbosity`, `responseFormat`, `rateLimit`, `requestTimeout`, `maxResponseSize`, and `maxSessionData`. `responseFormat` supports `compact` or `pretty`. For bearer-token authentication, use `apiToken`, which maps to `MAINWP_TOKEN`. If both credential methods are present, the username plus Application Password pair takes precedence. 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: ```json theme={null} { "schemaVerbosity": "compact" } ``` Or with an environment variable: ```bash theme={null} 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: ```json theme={null} { "schemaVerbosity": "compact", "allowedTools": ["list_sites_v1", "get_site_v1", "list_updates_v1", "run_updates_v1"] } ``` To hide destructive tools while keeping everything else available: ```json theme={null} { "blockedTools": [ "delete_site_v1", "delete_client_v1", "delete_tag_v1", "delete_site_plugins_v1", "delete_site_themes_v1" ] } ``` *** ## Safety Features ### Two-Step Confirmation By default, destructive operations use a preview-then-confirm flow. The MCP server first returns a preview and expects user approval before execution. Previews expire after 5 minutes. Some AI clients may not reliably follow every safety instruction, so use safe mode or blocked tools if you need stricter protection against accidental destructive actions. 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: ```json theme={null} { "requireUserConfirmation": false } ``` Or with an environment variable: ```bash theme={null} MAINWP_REQUIRE_USER_CONFIRMATION=false ``` ### Safe Mode Enable safe mode to block destructive operations entirely: ```json theme={null} { "safeMode": true } ``` Or with an environment variable: ```bash theme={null} MAINWP_SAFE_MODE=true ``` *** ## Troubleshooting ### Verify the Connection Test that your Dashboard REST API is reachable: ```bash theme={null} curl -I https://your-dashboard.com/wp-json/ ``` Test authentication: ```bash theme={null} curl -u "username:app-password" \ https://your-dashboard.com/wp-json/wp/v2/users/me ``` Test Abilities API access: ```bash theme={null} 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. ```json theme={null} { "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: ```json theme={null} { "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. ```json theme={null} { "maxSessionData": 104857600 } ``` **Response too large** * Increase `maxResponseSize` or reduce the response size with filters such as status filters or lower `per_page` values. ```json theme={null} { "maxResponseSize": 20971520 } ``` **Rate limit exceeded** * Wait and retry, or increase `rateLimit`. * Setting `rateLimit` to `0` disables rate limiting and is not recommended for production. ```json theme={null} { "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. ```bash theme={null} 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. ```bash theme={null} 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** ```bash theme={null} node dist/index.js 2>&1 | tee server.log ``` **Check server health directly** ```bash theme={null} 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: ```bash theme={null} 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 *** ## Related Resources * [Abilities API Overview](/api-reference/abilities-api/overview) - How abilities work * [Sites Abilities](/api-reference/abilities-api/sites) - Site management reference * [Updates Abilities](/api-reference/abilities-api/updates) - Update management reference * [Clients Abilities](/api-reference/abilities-api/clients) - Client management reference * [Tags Abilities](/api-reference/abilities-api/tags) - Tag management reference * [Batch Operations](/api-reference/abilities-api/batch-operations) - Queued job status reference * [GitHub Repository](https://github.com/mainwp/mainwp-mcp) - Source code and issues * [Configuration Reference](https://github.com/mainwp/mainwp-mcp/blob/main/docs/configuration.md) - Repository configuration details * [Security Guide](https://github.com/mainwp/mainwp-mcp/blob/main/docs/security.md) - Credential and trust-model guidance * [Example Prompts](https://github.com/mainwp/mainwp-mcp/blob/main/docs/example-prompts.md) - Sample prompts for common workflows * [Troubleshooting](https://github.com/mainwp/mainwp-mcp/blob/main/docs/troubleshooting.md) - Repository troubleshooting reference