BeTheme MCP Server

A secure, agent-friendly MCP server that turns one or more BeTheme-powered WordPress sites into a backend-equivalent environment for an AI agent.

┌──────────────────────────────────────────────────────────────┐
│  BeTheme MCP Server                                          │
│  Agent-driven WordPress + BeTheme administration             │
│  Pages • Templates • Plugins • WooCommerce • BeBuilder       │
└──────────────────────────────────────────────────────────────┘

What this project does

This project lets an AI agent manage BeTheme-powered WordPress sites without logging into wp-admin. It exposes MCP tools for:

• creating, editing, publishing, and deleting pages

• reading and writing BeBuilder payloads (mfn-page-items)

• creating and updating BeTheme templates (headers, footers, archives, popups, etc.)

• listing, activating, deactivating, and installing plugins

• returning site context and capabilities so the agent knows what it can do

The design is built for agencies: one local MCP server can connect to many client sites, each with its own URL and API key.

Architecture — what runs where

The project has two parts. Almost all business logic lives in the WordPress plugin. The local Node process is only a thin protocol adapter between the MCP client and the REST bridge.

flowchart LR
    A[MCP client e.g. Claude Desktop] -->|stdio| B[Local Node MCP server]
    B -->|HTTPS + HMAC signed| C[WordPress REST API]
    C --> D[BeTheme MCP Bridge plugin]
    D --> E[WordPress + BeTheme]

Part 1 — WordPress bridge plugin (plugin/betheme-mcp-bridge.php)

This runs on the web server inside WordPress. It:

• registers REST routes under /wp-json/betheme-mcp/v1/

• authenticates every request with an API key + HMAC-SHA256 request signature

• enforces WordPress capability checks (edit_pages, edit_theme_options, activate_plugins, etc.)

• sanitizes input, allow-lists BeTheme meta keys, and stores builder payloads in BeTheme's native format

• audits every action through the betheme_mcp_audit hook

• applies per-key rate limiting

Part 2 — Local MCP server (src/server.js)

This is a small Node.js process that runs on the machine where the AI agent runs. It:

• speaks the MCP protocol over stdin/stdout

• validates tool arguments against the declared JSON schema

• routes each tool call to the correct WordPress bridge endpoint

• supports multiple sites through a site argument or per-site configuration

Why does the MCP server run locally?

MCP clients today (Claude Desktop, etc.) usually launch an MCP server as a local child process over stdio. That local process can then talk to remote APIs. We keep the local part as thin as possible: it has no WordPress business logic, no database access, and no plugin installation logic. If your MCP client supports SSE, you can also host the Node server on your own infrastructure and point the client at it.

Installation — single site

1. WordPress requirements

• WordPress 6.4+ with the BeTheme theme active

• PHP 8.2+

• HTTPS recommended in production

2. Install the bridge plugin

1. Copy plugin/betheme-mcp-bridge.php into your WordPress site's wp-content/plugins/ directory.

2. In wp-admin, go to Plugins and activate BeTheme MCP Bridge.

3. Open wp-config.php and add a secure API key:

   define('BETHEME_MCP_API_KEY', 'replace-with-a-long-random-key');

4. Optional but recommended policy flags:

   define('BETHEME_MCP_AUDIT_LOG', true);
   define('BETHEME_MCP_ALLOW_PLUGIN_INSTALL', false);

5. Verify the bridge is reachable:

   curl -H "X-API-Key: replace-with-a-long-random-key" \
        https://your-site.test/wp-json/betheme-mcp/v1/health

   You should get {"ok":true,"site":"..."}.

3. Install and run the local MCP server

1. Clone this repository on the machine where your AI agent runs:

   git clone <repo-url> betheme-mcp
   cd betheme-mcp
   npm install

2. Create the environment file:

   cp .env.example .env

3. Edit .env:

   BETHEME_MCP_API_KEY=replace-with-a-long-random-key
   BETHEME_MCP_BASE_URL=https://your-site.test
   BETHEME_MCP_TIMEOUT_MS=10000

4. Start the server:

   npm start

5. Verify with the demo harness:

   npm run demo

4. Connect your MCP client

Pick the client you use and add the server configuration. In every case the local Node process is the same; only the client's config file or settings change.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "betheme": {
      "command": "node",
      "args": ["/absolute/path/to/betheme-mcp/src/server.js"]
    }
  }
}

ChatGPT Desktop

OpenAI's ChatGPT Desktop does not currently support local MCP servers. If support is added, the configuration file is expected to use the same mcpServers format as Claude Desktop. Use the same JSON structure and check OpenAI's documentation for the exact file location.

Copilot via VS Code

VS Code's Copilot Chat can use MCP servers configured in your user settings. Open Settings (JSON) (Cmd/Ctrl + Shift + P → Preferences: Open User Settings (JSON)) and add:

{
  "chat.mcp.servers": {
    "betheme": {
      "command": "node",
      "args": ["/absolute/path/to/betheme-mcp/src/server.js"]
    }
  }
}

The exact setting name may vary across VS Code versions (chat.mcp.servers, chat.mcp.serverDefinitions, or github.copilot.chat.mcpServers). If one setting is not recognized, try the next or check the latest VS Code MCP documentation.

GitHub Copilot Desktop

There is currently no standalone "GitHub Copilot Desktop" application that exposes local MCP server configuration. Use Copilot via VS Code above, or use Copilot in any editor that supports MCP server settings.

After saving the configuration, restart the client. The agent can now call tools such as list_pages, create_page, save_page_builder_payload, and list_plugins.

Installation — multi-site (agency setup)

Agencies can manage many client sites from one local MCP server. There are two ways to configure multiple sites.

Option A: sites.json file (recommended)

1. Copy the example file:

   cp sites.json.example sites.json

2. Edit sites.json:

   [
     {
       "name": "client-a",
       "baseUrl": "https://client-a.test",
       "apiKey": "key-for-client-a",
       "timeoutMs": 10000
     },
     {
       "name": "client-b",
       "baseUrl": "https://client-b.test",
       "apiKey": "key-for-client-b",
       "timeoutMs": 10000
     }
   ]

3. Restart npm start.

Option B: environment variable

In .env, set a single JSON array:

BETHEME_MCP_SITES=[{"name":"client-a","baseUrl":"https://client-a.test","apiKey":"key-for-client-a"},{"name":"client-b","baseUrl":"https://client-b.test","apiKey":"key-for-client-b"}]

BETHEME_MCP_SITES overrides sites.json. The single-site variables are ignored when multi-site configuration is present.

Using multiple sites in conversation

The agent can list configured sites with list_sites. For any other tool, pass the site argument:

• list_pages → lists pages from the first/default site

• list_pages with {"site":"client-a"} → lists pages from client-a

• create_page with {"title":"Home","site":"client-b"} → creates a page on client-b

If site is omitted, the first site in the configuration is used.

Multiple sites from the agent's point of view

You can tell the agent:

"List the sites you can access, then create a homepage on client-a and a contact page on client-b."

The agent will call list_sites, pick the correct aliases, and route each action to the right WordPress installation.

How authentication works

Every request from the local MCP server to WordPress is authenticated in two ways:

1. API key — sent in the X-API-Key header and compared against BETHEME_MCP_API_KEY in wp-config.php.

2. HMAC request signature — the local server signs the request with HMAC-SHA256(method|timestamp|body) and sends it in X-Request-Signature. The bridge rejects requests outside a 5-minute replay window or with an invalid signature.

Keep the API key secret. Use HTTPS in production so the key and signatures are protected in transit.

Capability model

The bridge checks WordPress capabilities on every route:

The authenticate tool returns the bridge-level capabilities the current context supports.

Security model

• Authentication: API key + HMAC-SHA256 request signing with timestamp replay window.

• Authorization: per-route WordPress capability checks.

• Input validation: JSON Schema validation on the MCP side; sanitization and allow-lists on the PHP side.

• Meta allow-listing: only known BeTheme page/template meta keys are accepted.

• Payload hardening: builder payloads are stored in BeTheme's native format and capped at 1 MB.

• Rate limiting: per-API-key token bucket using WordPress transients.

• Audit logging: every administrative action is logged via betheme_mcp_audit and optionally to the PHP error log.

Development and testing

Run the local test and lint suite:

npm test
npm run lint
php -l plugin/betheme-mcp-bridge.php

All three should pass before any release.

Documentation

• docs/README.md — documentation index

• docs/sdd/02-architecture.md — system architecture

• docs/sdd/07-mcp-capability-surface.md — MCP tools, resources, and prompts

• docs/sdd/06-security-and-owasp.md — security posture

Release and versioning

Releases are published through GitHub Actions when a v* tag is pushed. Version numbers align with the BeTheme version they target, plus an alpha suffix. The current alpha is 28.5.4-alpha.003.

Alpha release notice

This project is currently an alpha release and is still under quality assurance. It is intended for evaluation, integration testing, and controlled internal use, not for production deployment until QA is complete.