MainWP MCP Server

A MainWP Labs project, powered by MainWP

Manage your whole WordPress network by talking to your AI assistant. MainWP MCP Server connects Claude, Cursor, OpenAI Codex, VS Code Copilot, and other MCP-compatible tools to your MainWP Dashboard, so you can ask in plain English:

"Which sites have pending plugin updates?"

"Update WooCommerce everywhere it's behind."

"Which client sites are disconnected right now?"

The server is a small program that runs on your own computer, alongside your AI tool. Nothing new is installed on your Dashboard or your child sites. Your Dashboard stays in control: it exposes only the tools you allow, and by default anything classified as destructive stops for your confirmation before it runs.

What You Can Do

• Site Management: List sites, check connection status, sync data, add or remove child sites
• Update Management: See pending updates across all sites, apply core/plugin/theme updates
• Plugin and Theme Control: View installed plugins and themes, activate or deactivate them
• Client Organization: Manage client records, assign sites to clients, track costs
• Bulk Operations: Sync, reconnect, or check connectivity across dozens of sites at once

Built for WordPress agencies and site managers who want AI assistance with their MainWP workflows.

Documentation

Full documentation lives at docs.mainwp.com/mcp-server:

• Quickstart with screenshots, if this is your first MCP server
• Setup for every AI client: Claude Desktop, Claude Code, Cursor, VS Code Copilot, OpenAI Codex, ZenCoder, and others
• Safety & Permissions: the confirmation flow, safe mode, and tool filtering
• Prompt Cookbook: ready-to-use prompts by task
• Configuration Reference and Troubleshooting

Quick Start

Requirements: Node.js >=20.19.0 and MainWP Dashboard 6.0+

1. Create an Application Password. This is a separate password WordPress issues for tools like this one; it never changes your login and you can revoke it at any time.

1. Log into your MainWP Dashboard as an administrator
2. Go to Users > Profile (click your username in the top right)
3. Scroll to the Application Passwords section
4. Enter a name like "MainWP MCP Server" and click Add New Application Password
5. Copy the generated password immediately (it is only shown once; spaces are fine either way)

Tip: Create a dedicated WordPress user for API access rather than using your main admin account. It keeps the audit trail clean and is easy to revoke later.

2. Add the server to your AI tool. For Claude Desktop and most other MCP clients, the config block looks like this:

{
  "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"
      }
    }
  }
}

Config file locations and variants for each client are in the client setup guide. Prefer a central credentials file, or manage several Dashboards? See the configuration reference.

3. Restart your AI tool and ask: "List all my sites". A working setup returns your child sites by name and URL.

Start bounded. You don't have to expose every tool on day one. Grant the smallest set your workflow needs and widen from there. See Restrict Available Tools.

Claude Code plugin

Claude Code can install the server, an agent skill, and a set of /mainwp:* workflow commands in two steps:

/plugin marketplace add mainwp/mainwp-mcp
/plugin install mainwp@mainwp-mcp

Credentials still come from your environment. The plugin carries no credential values; the server inherits MAINWP_URL, MAINWP_USER, and MAINWP_APP_PASSWORD from the environment Claude Code runs it in. If you already added a mainwp server by hand, move everything in its env block (credentials and any MAINWP_* settings such as safe mode or tool filters) into the environment that launches Claude Code, then remove that entry: Claude Code treats the plugin's server as a duplicate and never starts it, so the hand-added entry silently wins. Setup details are at docs.mainwp.com/mcp-server; the plugin's own conventions are in docs/plugin.md.

Alongside the server, the plugin installs the mainwp-dashboard agent skill. It loads automatically when a task involves managing sites through MainWP and teaches the agent how this server behaves: the tool catalog comes from your Dashboard at runtime, destructive operations stop for user confirmation, safe mode blocks destructive calls at execution, and tool filtering can remove tools on purpose. The plugin also registers ten workflow commands:

| Command | What it does | | --------------------------- | ----------------------------------------------------------------------- | | /mainwp:setup | Diagnose the MCP connection and configuration without exposing secrets | | /mainwp:tools | Show what your Dashboard exposes, grouped by capability | | /mainwp:network-summary | Executive summary of the network: site counts, update totals, health | | /mainwp:site-report | Detailed report for one site: overview, updates, health, next actions | | /mainwp:troubleshoot-site | Diagnose one site: connectivity, sync health, pending updates, errors | | /mainwp:update-workflow | Plan a safe update run: what to update, in what order, on which sites | | /mainwp:security-audit | Security-focused audit: outdated core, plugins, themes | | /mainwp:backup-status | Backup coverage and freshness across managed sites | | /mainwp:maintenance-check | Maintenance sweep across every site, ranked by urgency | | /mainwp:performance-check | Performance indicators for one site or the network, from Dashboard data |

For development, clone and build instead of npx:

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

First-run setup

If the server starts without a Dashboard URL or credentials, it does not fail to launch. It connects to your AI client in setup mode: the MainWP tools stay hidden and two setup tools take their place, so you can finish the configuration in the conversation instead of hunting through stderr.

• mainwp_get_setup_status reports what is missing and returns the setup instructions for your assistant to relay. If credentials are present but the Dashboard was unreachable at startup, calling it again retries the connection with the credentials already loaded.
• mainwp_configure takes a Dashboard URL, username, and Application Password, verifies them against the Dashboard, and saves them.

Two ways to finish setup:

Adding the credentials yourself is the recommended path. Put MAINWP_URL, MAINWP_USER, and MAINWP_APP_PASSWORD in the env block of this server's entry in your MCP client config (see Quick Start) or in ~/.config/mainwp-mcp/settings.json, then restart the client. The password never passes through the conversation.

Pasting them in chat is also fine. Your assistant collects the three values and calls mainwp_configure. The server verifies them, writes them to ~/.config/mainwp-mcp/settings.json with owner-only permissions (0600, in a 0700 directory), and scrubs the password from its own logs and from every response. An Application Password is separate from your WordPress login password and you can revoke it from your profile at any time. Worth knowing before you choose: the password also becomes part of your chat history, which your AI client and provider may retain. If that bothers you later, revoke the password and create a new one.

Once configuration succeeds, the full tool list appears in the same session for clients that honor MCP list-changed notifications. Clients that do not refresh on their own need a reconnect or restart.

mainwp_configure refuses rather than saving something that would be ignored or overridden:

• Any connection environment variable (MAINWP_URL, MAINWP_USER, MAINWP_APP_PASSWORD, MAINWP_TOKEN) is set. Environment variables outrank the file it writes, so finish setup there.
• A settings.json exists in the server's working directory. That file is loaded first and would permanently shadow the saved credentials.
• The server already has credentials loaded, whether or not they are currently working. Setup will not replace existing credentials from chat. If the connection is failing, mainwp_get_setup_status retries with the credentials already loaded; to change them, edit the config file or the client's env block.

It writes only those three connection fields, never security settings, and blocking mainwp_configure through MAINWP_BLOCKED_TOOLS removes chat-based setup entirely while leaving the manual path documented.

Why setup will not replace credentials you already have

Chat-based setup can get you connected the first time, but it can never overwrite a connection you set up yourself. That line is deliberate, and it is worth knowing where it costs you something.

The reason is that an assistant acts on text, and text can come from places you did not intend. A page it read, a site name, or an ability description returned by a server could carry instructions aimed at the assistant rather than at you. If setup could overwrite a working configuration, that kind of injected instruction could quietly repoint your server at someone else's Dashboard, and every command you ran afterwards would go there. Restricting setup to the case where there is nothing to overwrite removes that possibility, because a server that has no credentials has nothing worth stealing.

A tempting middle ground is to allow it when the stored credentials are provably wrong, since the Dashboard rejected them with an authentication error. We do not do that, because it would let the remote side decide when your local configuration may be replaced: a Dashboard that had been compromised, or a connection someone was tampering with, could reject a valid login on purpose to unlock the replacement path, without ever knowing your password.

The cost is real, and it lands in one place. If you rotate the Application Password in WordPress, or the stored one is wrong for any other reason, retrying will not help, because the retry reuses the same credentials the Dashboard is already refusing. You have to put the new password in ~/.config/mainwp-mcp/settings.json or your client's env block yourself and restart the client. That is the same edit you would have made to set the server up manually in the first place, and it takes a minute.

Configuration

| Variable | Required | Default | Description | | ---------------------------------- | -------------- | ---------- | ------------------------------------------------------------------------------------------------------ | | MAINWP_URL | Yes | | Base URL of your MainWP Dashboard | | MAINWP_USER | For basic auth | | WordPress admin username | | MAINWP_APP_PASSWORD | For basic auth | | WordPress Application Password | | MAINWP_TOKEN | No | | Compatibility only; the Abilities API is expected to reject bearer tokens. Use an Application Password | | MAINWP_SKIP_SSL_VERIFY | No | false | Skip SSL verification (dev only) | | MAINWP_ALLOW_HTTP | No | false | Allow HTTP URLs (credentials sent in plain text) | | MAINWP_SAFE_MODE | No | false | Block destructive operations | | MAINWP_REQUIRE_USER_CONFIRMATION | No | true | Require two-step confirmation for destructive operations | | MAINWP_ALLOWED_TOOLS | No | | Whitelist of tools to expose | | MAINWP_BLOCKED_TOOLS | No | | Blacklist of tools to hide | | MAINWP_SCHEMA_VERBOSITY | No | standard | standard or compact | | MAINWP_RESPONSE_FORMAT | No | compact | Response JSON formatting: compact or pretty | | MAINWP_RATE_LIMIT | No | 60 | Maximum API requests per minute (0 disables) | | MAINWP_REQUEST_TIMEOUT | No | 30000 | Request timeout in milliseconds | | MAINWP_MAX_RESPONSE_SIZE | No | 10485760 | Maximum single 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 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 | | MAINWP_ABILITY_NAMESPACES | No | mainwp | Comma-separated ability namespace allowlist |

"Required" means required to connect to a Dashboard, not required to start. With no URL and no credentials the server still launches in setup mode and you can supply all three values from the conversation instead. See First-run setup.

⚠️ Security Warning: SSL Verification

Setting MAINWP_SKIP_SSL_VERIFY=true disables SSL certificate verification, making your connection vulnerable to man-in-the-middle (MITM) attacks. Only use for local development with self-signed certificates or isolated test environments. Never use in production or on untrusted networks.

Instead of environment variables, you can use a settings.json file in the working directory or ~/.config/mainwp-mcp/settings.json; environment variables override file settings. A working-directory settings.json cannot loosen security settings: requireUserConfirmation: false, skipSslVerify: true, and allowHttp: true are ignored there with a warning on stderr. Set those through environment variables or the per-user file. Field names, the settings-to-variable mapping, and per-setting detail are in the Configuration Reference.

Tools

Around 60 tools, organized by category (the exact count varies by Dashboard version):

| Category | Tools | Reference | | ---------------- | ----- | ---------------------------------------------------------------------------------------- | | Sites | 30 | Sites Abilities | | Updates | 13 | Updates Abilities | | Clients | 11 | Clients Abilities | | Tags | 7 | Tags Abilities | | Batch Operations | 1 | Batch Operations |

Tool names drop the mainwp/ namespace and use underscores: the ability mainwp/list-sites-v1 is the tool list_sites_v1. Naming rules, the built-in MCP resources (mainwp://abilities, mainwp://status, and friends), and namespace prefixing for third-party abilities are covered in Tools & Resources.

Safety

Operations classified as destructive (the deletion tools, plus any ability that does not declare itself non-destructive) use a two-step flow by default: the server returns a preview and a one-time token, your AI shows you what will be affected, and only your explicit approval executes it. Disabling the flow (MAINWP_REQUIRE_USER_CONFIRMATION=false) removes that gate. Safe mode (MAINWP_SAFE_MODE=true) blocks destructive operations entirely, and tool filtering can remove them from the AI's view altogether. The full model, including what safe mode does and does not protect against, is on Safety & Permissions; the underlying trust and credential model is in the Security Model.

Contributing

npm ci             # install dependencies
npm run dev        # run in watch mode
npm run inspect    # test with MCP Inspector
npm test           # run tests
npm run lint       # check code style
npm run format     # fix formatting

CI runs lint, format check, type check, tests, and build on every pull request.

When changing configuration options, update both the environment-variable table above and the docs-site configuration reference; they are maintained in parallel.

.agents/skills/mainwp-dashboard is the canonical copy of the cross-agent skill, read directly by Codex CLI and other agent-skills clients and mirrored into the Claude Code plugin by npm run sync-skill. Edit it there, never in plugins/. See docs/plugin.md.

License

GPL-3.0. See LICENSE.