@mainwp/mcp

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.

• Log into your MainWP Dashboard as an administrator
• Go to Users > Profile (click your username in the top right)
• Scroll to the Application Passwords section
• Enter a name like "MainWP MCP Server" and click Add New Application Password
• 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

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

⚠️ 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.