<p align="center"> <img src="assets/icon.svg" width="128" height="128" alt="MainWP MCP Bridge icon"> </p>

MainWP MCP Bridge

Give AI agents, coding assistants, and GitHub Actions policy-controlled access to your MainWP Dashboard—through the MCP connection you already use, a dedicated MainWP server, or both.

MainWP MCP Bridge is free and open source. It exposes the live WordPress Abilities registered by MainWP in two complementary ways:

• Existing-server mode: publishes MainWP abilities to the active Novamira or WordPress MCP Adapter server, so an AI client needs no second MCP configuration.
• Dedicated-server mode: registers /wp-json/mcp/mainwp with direct MainWP tool names, richer confirmation tokens, prompts, and resources.

Download the latest release

Why use this plugin?

Novamira and WordPress MCP Adapter provide the MCP protocol, HTTP transport, authentication, and server framework. MainWP provides the site-management operations. This bridge connects those layers while letting each administrator choose the simplest useful exposure model.

Benefits include:

• First-class MainWP tools when dedicated: agents call list_sites_v1, list_updates_v1, and other MainWP operations directly instead of navigating a generic ability discovery/execution interface.
• One connection when preferred: publish MainWP abilities through the site's existing MCP server and keep the AI client configuration it already uses.
• Always-current discovery: tools come from the abilities registered by the installed MainWP Dashboard, so runtime behavior does not depend on a handwritten PHP inventory.
• Safer automation: destructive operations fail closed; dedicated mode can require a preview plus a user-bound, one-time confirmation token.
• Optional isolation: enable the dedicated /wp-json/mcp/mainwp endpoint alone or alongside existing-server ability access.
• Agent guidance included: eight workflow prompts cover troubleshooting, maintenance, updates, reporting, security, backups, and performance.
• Automation-ready authentication: remote clients use standard WordPress Application Passwords over HTTPS; the plugin stores no client credentials.
• Controlled exposure: administrators can configure namespaces, allowlists, blocklists, safe mode, schema verbosity, and per-user rate limits.
• Dashboard updates: future releases are discovered and installed through the normal WordPress Plugins screen using the exact packaged GitHub Release asset.

Architecture

The plugin is an integration layer, not a replacement for MainWP, Novamira, or WordPress MCP Adapter. It contains no MainWP site-management business logic and bundles no MCP Adapter source.

flowchart LR
    Agent["AI agent or GitHub Action"]
    Auth["HTTPS + WordPress Application Password"]
    Adapter["Novamira or WordPress MCP Adapter"]
    Mode{"Exposure mode"}
    Existing["Existing adapter server and generic ability tools"]
    Server["Dedicated mainwp MCP server"]
    Bridge["Discovery, schemas, naming, policy, confirmation"]
    Abilities["WordPress Abilities API"]
    MainWP["MainWP Dashboard"]

    Agent --> Auth --> Adapter --> Mode
    Mode --> Existing --> Abilities
    Mode --> Server --> Bridge --> Abilities --> MainWP
    Abilities --> MainWP

Component	Responsibility
MainWP Dashboard	Registers and executes the real site-management abilities.
WordPress Abilities API	Supplies the live ability registry and delegates permission checks.
Novamira or WordPress MCP Adapter	Handles MCP JSON-RPC, HTTP transport, sessions, and WordPress authentication.
MainWP MCP Bridge	Publishes selected MainWP abilities to an existing server and/or builds the dedicated server with direct tools, prompts, resources, and confirmation tokens.
AI client	Connects with an authorized WordPress user and decides which exposed tools to call.

For existing-server mode, the bridge uses WordPress's supported wp_register_ability_args filter to add mcp.public metadata only to policy-selected MainWP abilities. The adapter's own discover-abilities, get-ability-info, and execute-ability tools then expose them without another endpoint. For dedicated mode, the bridge registers a separate server through WP\MCP\Core\McpAdapter::create_server(). It does not fork the adapter or replace existing Novamira routes.

Requirements

• WordPress 6.9 or newer
• PHP 7.4 or newer
• MainWP Dashboard 6.0 or newer
• MCP Adapter 0.5 or newer supplied by either:
  • WordPress MCP Adapter, or
  • Novamira with the compatible bundled WP\MCP\Core\McpAdapter

WordPress cannot express an OR relationship in Requires Plugins. The plugin declares MainWP as a dependency and checks the adapter provider at runtime. If no compatible provider is active, MCP exposure remains inactive and administrators receive an actionable notice rather than a fatal error.

Installation

1. Install and activate MainWP Dashboard.
2. Install WordPress MCP Adapter 0.5+ or activate a compatible Novamira installation.
3. Download the versioned mainwp-mcp-bridge-X.Y.Z.zip asset from the latest GitHub release.
4. In WordPress, open Plugins > Add Plugin > Upload Plugin, install the ZIP, and activate it.
5. Open Settings > MainWP MCP Bridge and confirm that every dependency is healthy.
6. Choose Existing MCP server only, Dedicated MainWP server only, or Existing and dedicated servers.
7. For existing-server mode, keep using the MCP client connection you already configured. For dedicated mode, create a WordPress Application Password and copy the generated client configuration.

Version 0.2.0 is the updater bootstrap release. Install it manually once if you are currently on 0.1.0; releases after 0.2.0 will appear in the normal WordPress Dashboard update flow.

WordPress Dashboard updates

The plugin checks this repository's public, non-prerelease GitHub Releases and integrates the result with WordPress's standard plugin update UI. No GitHub token or update credential is stored.

flowchart LR
    Release["Tagged GitHub Release"]
    Asset["mainwp-mcp-bridge-X.Y.Z.zip"]
    Checker["Bundled Dashboard updater"]
    WordPress["Plugins > Updates"]

    Release --> Asset --> Checker --> WordPress

The updater accepts only assets named mainwp-mcp-bridge-X.Y.Z.zip. If the expected asset is absent, it refuses to fall back to GitHub's automatically generated source archive, which does not have the distributable WordPress plugin layout.

WordPress normally checks for updates twice daily. Administrators can also use the Check for updates action on the Plugins screen. Release descriptions provide the details/changelog content, while the packaged icon supplies the update-row artwork.

Existing MCP server mode

Choose Existing MCP server only when Novamira or the standalone WordPress MCP Adapter is already connected to the AI client. The bridge marks the selected MainWP abilities as MCP-public during their normal WordPress registration. They appear through the provider's generic ability discovery and execution tools; /wp-json/mcp/mainwp is not registered and no second client entry is needed.

Allow/block filters, safe mode, MainWP's native confirm/dry_run controls, underlying ability permissions, and the per-user rate limit remain enforced. The dedicated endpoint is still the better choice when an agent benefits from 62 direct tool definitions, one-time cross-request preview tokens, compact schemas, the eight workflow prompts, or the four bridge resources.

Dedicated MCP client configuration

Keep credentials in a secret store or environment variables. Never commit an Application Password.

{
  "mcpServers": {
    "mainwp": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://dashboard.example.com/wp-json/mcp/mainwp",
        "WP_API_USERNAME": "automation-user",
        "WP_API_PASSWORD": "APPLICATION_PASSWORD_FROM_A_SECRET_STORE"
      }
    }
  }
}

Application Passwords require HTTPS unless WordPress explicitly recognizes a local development environment.

Live tool mapping

Every server build calls wp_get_abilities() and selects the configured namespaces. The default namespace is mainwp, with a compatibility baseline of 62 MainWP 6 tools.

• mainwp/list-sites-v1 becomes list_sites_v1.
• A secondary namespace such as vendor-extension/do-thing-v1 becomes vendor_extension__do_thing_v1.
• Blocked or non-allowlisted tools disappear from discovery, invocation, and generated help.
• Authorization remains delegated to each underlying MainWP ability after bridge-only control arguments are removed.

The generated contract records expected schemas and behavior for testing and drift detection. It never replaces live discovery.

Safety model

Only an explicit annotations.destructive === false is treated as non-destructive. Missing or malformed annotations fail closed.

Policy order is fixed:

1. Apply the blocked-tools and allowlist policy.
2. Block destructive tools when safe mode is active.
3. Require the configured confirmation workflow.
4. Delegate execution to the live MainWP ability.

For destructive tools that declare confirmation support:

1. Call with confirm:true to request a preview.
2. Show the preview or exact operation to the user and obtain explicit approval.
3. Within five minutes, call again with user_confirmed:true and the returned confirmation_token.

Tokens persist across HTTP requests in WordPress transients. Each token is bound to the authenticated user, WordPress site, tool, and canonical non-control arguments. Tokens are single-use, expire after five minutes, reject replay and argument swapping, and are capped at 100 pending tokens per user.

Stable workflow result codes include SAFE_MODE_BLOCKED, CONFIRMATION_REQUIRED, PREVIEW_REQUIRED, PREVIEW_EXPIRED, CONFIRMATION_UNSUPPORTED, DRY_RUN_NOT_SUPPORTED, CONFLICTING_PARAMETERS, and NO_CHANGE.

Prompts and resources

Eight guided prompts are included:

• troubleshoot-site
• maintenance-check
• update-workflow
• site-report
• network-summary
• security-audit
• backup-status
• performance-check

Four static resources help agents understand the live surface:

• mainwp://abilities
• mainwp://categories
• mainwp://status
• mainwp://help

MCP Adapter 0.5 does not expose resource-template registration. Use get_site_v1 for an individual site and mainwp://help for per-tool guidance.

Settings

Only administrators can modify the validated mainwp_mcp_bridge_settings option.

array(
    'enabled'                => true,
    'exposure_mode'          => 'dedicated', // existing, dedicated, or both.
    'safe_mode'              => false,
    'require_confirmation'   => true,
    'schema_verbosity'       => 'standard',
    'ability_namespaces'     => array( 'mainwp' ),
    'allowed_tools'          => array(),
    'blocked_tools'          => array(),
    'rate_limit_per_minute'  => 60,
)

The settings screen discovers the currently registered tools and renders Allowed tools and Blocked tools as multi-select controls. Administrators no longer need to type or guess normalized tool names. Dashboard URL, credentials, SSL bypass, retry, request-timeout, response-size, and session-byte settings are intentionally absent because ability execution is local and in-process.

Contract synchronization

The static synchronizer accepts a release ZIP, extracted directory, or GitHub tag and never executes the source package:

node tools/sync-upstream.mjs C:\path\to\mainwp-mcp.zip --check
node tools/sync-upstream.mjs vNEXT --write

Compatible data-only changes can regenerate the committed contract. Changes to policy, confirmation, naming, or schema behavior fail closed and produce a machine-readable report for human or AI-assisted review. See PORTING.md.

Development

composer install
composer test
npm run build
python tools/inspect-dist.py dist/mainwp-mcp-bridge-0.3.0.zip

The release ZIP contains runtime PHP, the single production update dependency and its license, assets, the generated PHP contract, and end-user documentation. It excludes development dependencies, source archives, tests, CI configuration, and development tooling.

The project includes PHPUnit, PHPCS, PHPStan, contract drift checks, Plugin Check, package inspection, and disposable WordPress/MainWP integration workflows.

Frequently asked questions

Does this replace Novamira or WordPress MCP Adapter?

No. One of those providers is required. The adapter supplies MCP transport and authentication; this plugin publishes MainWP abilities into that provider, adds the optional dedicated MainWP server, and applies the selected safety contract.

Do I need to configure a second MCP server in my AI client?

No. Select Existing MCP server only and continue using the site's current Novamira or WordPress MCP Adapter connection. Select Dedicated or Both only when you want the direct MainWP tools and the bridge's richer endpoint-specific features.

Why would I still use the dedicated endpoint?

This bridge gives agents stable, directly discoverable MainWP tools plus purpose-built prompts, resources, policy controls, and confirmation behavior. That is easier to use and safer to automate than asking every client to rediscover and reconstruct the MainWP surface.

Does it copy MainWP functionality?

No. The bridge delegates permission checks and execution to MainWP's live abilities.

Does it store my MainWP or MCP credentials?

No. Remote clients authenticate through WordPress. Keep Application Passwords in the client's secret store.

How do plugin updates work?

Version 0.2.0 and later query public GitHub Releases and use the versioned distributable ZIP attached to each release. Install 0.2.0 manually if upgrading from 0.1.0; subsequent versions can be installed from the WordPress Plugins screen.

Is it free?

Yes. MainWP MCP Bridge is licensed under GPL-3.0-or-later and can be used, audited, modified, and shared under that license.

Contributing and security

Issues and pull requests are welcome. Please include reproducible steps and avoid posting Application Passwords, site URLs, or other secrets.

For security-sensitive reports, use GitHub's private vulnerability reporting for this repository rather than opening a public issue.

License

GPL-3.0-or-later. See LICENSE.txt.