zen-mcp-bridge

# Zen MCP Bridge **Connect your WordPress site to Claude.ai via the Model Context Protocol — giving Claude read-only access to your plugins, themes, post types, custom fields, database, source files, logs, hooks, and more.** Zen MCP Bridge turns your WordPress site into an MCP server that Claude.ai can connect to. Once connected, Claude can inspect your site's architecture in real time — plugins, database schema, source code, ACF fields, REST routes, cron jobs — so it can write plugins, debug issues, and answer questions that are tailored to your exact setup instead of to WordPress in general. **Claude gets read-only access by default. It cannot write, delete, or modify anything unless you explicitly turn write mode on.** - **Website:** https://guramzhgamadze.github.io/zen-mcp-bridge/ - **WordPress.org:** https://wordpress.org/plugins/zen-mcp-bridge/ - **Requires:** WordPress 6.9+ · PHP 8.0+ - **Licence:** GPL-2.0-or-later - **Current version:** 3.2.3 --- ## Features - **Full OAuth 2.1 authorization server** with PKCE (S256), dynamic client registration (RFC 7591), and auto-discovery endpoints (RFC 8414 + RFC 9728). - **Bearer Token auth** as a simpler alternative to OAuth — never expires. - **Configurable OAuth token lifetime** — 1 hour, 24 hours, 7 days or 30 days, switchable from the admin settings page, with an emergency "Revoke All" button for instant invalidation. - **25 read-only MCP tools** covering every major aspect of a WordPress site — including code search, transients, Action Scheduler, WooCommerce and Elementor inspectors. - **Opt-in write mode** (off by default) — six scoped, audited write tools: draft-only posts, allowlisted options, plugin toggling, cache clearing, term creation. OAuth needs an explicit consent-screen write grant (`claudeai:write`); deleting, publishing, user management and write SQL are never possible. - **MCP resources & prompts** — site snapshots at `wordpress://` URIs and canned prompts for site analysis, debugging and plugin writing. - **WordPress Abilities API bridge** — tools discoverable by the WP AI ecosystem (admin-only); stands down automatically when the official AI Provider for Anthropic plugin is active. - **MCP spec 2025-11-25 compliant**, including `client_id_metadata_document_supported`, scope in `WWW-Authenticate`, and `description` in `serverInfo`. - **Rate limiting** — 120 tool calls per minute per IP. - **Security hardened** — path traversal guards, credential redaction, single-use auth codes, clickjacking protection, and more. - **Apache + FastCGI compatible** — Authorization header normalization built in. - **Zero dependencies** — pure WordPress, no Composer required. --- ## Requirements | Requirement | Version | |---|---| | WordPress | 6.9 or higher (for the Abilities API) | | PHP | 8.0 or higher | | MySQL / MariaDB | Any version supported by your WordPress install | --- ## Installation 1. Install through **Plugins → Add New** (search for "Zen MCP Bridge"), or from [WordPress.org](https://wordpress.org/plugins/zen-mcp-bridge/). With WP-CLI: ```bash wp plugin install zen-mcp-bridge --activate ``` 2. Go to **Settings → MCP Bridge** to find your endpoint URL and Bearer Token. 3. Flush rewrite rules: **Settings → Permalinks → Save Changes**. --- ## Connecting to Claude.ai There are two connection methods. Option A is the fastest. ### Option A — Bearer Token (simplest) 1. In Claude.ai, go to **Profile → Settings → Connectors → Add custom connector**. 2. Paste your MCP endpoint URL (shown in Settings → MCP Bridge): ``` https://your-site.com/wp-json/zen-mcp/v1/bridge ``` 3. Set auth type to **Bearer Token** (or **API Key**). 4. Paste the token from the settings page. 5. Save — Claude.ai connects immediately. ### Option B — OAuth 2.1 (browser login flow) Claude.ai discovers the OAuth server automatically via the `.well-known/` endpoints. If asked for details manually: | Field | Value | |---|---| | Authorization URL | `https://your-site.com/wp-json/zen-mcp/v1/oauth/authorize` | | Token URL | `https://your-site.com/wp-json/zen-mcp/v1/oauth/token` | | Client ID | `claude.ai` (any value except literally "Bearer Token") | | Scopes | `claudeai` | Claude.ai opens a browser window to your WordPress site, where you log in as an administrator and click **Allow Access**. --- ## Endpoints | Endpoint | Purpose | |---|---| | `POST /wp-json/zen-mcp/v1/bridge` | Main MCP JSON-RPC endpoint | | `GET/POST /wp-json/zen-mcp/v1/oauth/authorize` | OAuth 2.1 authorization | | `POST /wp-json/zen-mcp/v1/oauth/token` | OAuth 2.1 token exchange | | `POST /wp-json/zen-mcp/v1/oauth/register` | Dynamic client registration (RFC 7591) | | `GET /.well-known/oauth-authorization-server` | OAuth discovery (RFC 8414) | | `GET /.well-known/oauth-protected-resource` | Protected resource metadata (RFC 9728) | | `GET /authorize` · `POST /token` | Old-spec fallbacks (auto-proxied) | --- ## Available MCP tools ### Read-only | Tool | Description | |---|---| | `wp_get_site_info` | WP/PHP/MySQL versions, active theme, plugins, debug settings, upload dirs | | `wp_get_plugins` | All installed plugins — name, version, author, status | | `wp_get_themes` | All themes — version, author, parent theme, active state | | `wp_get_post_types` | All post types — labels, supports, taxonomies, REST base, post count | | `wp_get_taxonomies` | All taxonomies — object types, REST settings, term counts | | `wp_get_options` | WordPress options (credentials always redacted) | | `wp_query_posts` | Query any post type via `WP_Query` — post data, meta and terms | | `wp_get_db_schema` | All database tables — columns, types, row counts | | `wp_db_query` | Read rows from one table with filters/order/limit — identifiers whitelisted against the live schema, values parameterized (no raw SQL) | | `wp_list_files` | List files in any `wp-content` subdirectory, filtered by extension | | `wp_read_file` | Read any source file in `wp-content` (max 512 KB) | | `wp_get_logs` | Read `debug.log` or the PHP error log (last N lines) | | `wp_get_hooks` | Inspect `$wp_filter` — all registered actions and filters with priorities | | `wp_get_acf_fields` | All ACF field groups and fields (requires ACF) | | `wp_get_users` | List users with roles (passwords never returned) | | `wp_get_menus` | Navigation menus, assigned locations, and menu items with hierarchy | | `wp_get_cron_jobs` | All scheduled WP cron events — next run times, schedules and args | | `wp_get_active_widgets` | Active widget areas and widgets with their settings | | `wp_get_rest_routes` | All registered REST API routes with methods and namespaces | | `wp_search_code` | Search file contents across `wp-content` — file, line number, matching line | | `wp_get_post` | Single post by ID or slug — full content, meta, terms, featured image | | `wp_get_transients` | Transients with expiry and value preview (auth/secret values redacted) | | `wp_get_scheduled_actions` | Action Scheduler counts by status and next pending actions | | `wp_get_woocommerce` | WooCommerce overview — settings, counts, gateways, zones (no PII or keys) | | `wp_get_elementor` | Elementor overview — versions, kit settings, templates, experiments | ### Write (opt-in, off by default) | Tool | Description | |---|---| | `wp_create_draft_post` | Create a post as a **draft** — publishing always needs a human | | `wp_update_draft_post` | Edit an existing draft or pending post — published posts refused | | `wp_update_option` | Change an allowlisted option — identity, code and secret options hard-denied | | `wp_toggle_plugin` | Activate or deactivate an installed plugin — never this plugin itself | | `wp_clear_cache` | Flush object cache, rewrite rules, expired transients | | `wp_create_term` | Create a taxonomy term | --- ## Security ### Authentication - Bearer tokens are stored with `autoload = false` — never loaded on regular page requests. - Tokens are validated with `hash_equals()` to prevent timing attacks. - OAuth token lifetime is configurable (1 hour default, up to 30 days). Bearer Token auth never expires; only OAuth access tokens are time-limited. - Authorization codes expire after 10 minutes and are single-use — deleted immediately on redemption. - PKCE S256 is mandatory; plain code challenges are rejected. - The plugin's own token and config options are permanently blocked from `wp_get_options`. - **Revoke All OAuth Tokens** on the admin page for immediate emergency invalidation. Revocation uses an options-backed generation counter and registry, so it works correctly even behind a persistent object cache. ### Authorization - Only WordPress administrators (`manage_options`) can grant OAuth consent. - The consent page is protected against clickjacking via `X-Frame-Options: DENY` and `Content-Security-Policy: frame-ancestors 'none'`. - Write mode requires both the site-level toggle **and**, for OAuth clients, an explicit `claudeai:write` grant on the consent screen. ### File & database access - All file operations are contained within `wp-content` using `realpath()` plus separator-aware path checks (OWASP path traversal prevention). - Log file paths are validated against an allowlist of roots. - **There is no raw SQL.** `wp_db_query` builds a structured query itself: table and column identifiers are validated against the live schema and a strict pattern before being interpolated in backticks, while all values are bound through `$wpdb->prepare()`. The cost is no JOINs or aggregate expressions — single-table filtered reads only — and the benefit is no injection surface at all. - Secret redaction is applied in a shared helper used by every tool, not per-tool, so a secret cannot be read through a different exit. - `user_pass`, `user_activation_key`, and `SELECT *` on the users table are blocked outright. ### CORS & network - CORS headers on the sensitive `/bridge` endpoint are scoped to `claude.ai`, `app.claude.ai` and `www.claude.ai` only. The public `.well-known` discovery documents are open, as they are for every OAuth provider — they contain no secrets. - DNS rebinding protection via a per-request origin check. - `X-Content-Type-Options: nosniff` on every plugin response. - `WWW-Authenticate` on 401 responses points Claude.ai to the OAuth discovery endpoint, with the required scope parameter. - Apache + FastCGI Authorization header normalization — no `.htaccess` workaround needed. ### External service Claude.ai (Anthropic) connects **inbound** to your site; the plugin never makes an outbound request to it. What Claude can read is exactly what the tools above expose, gated by your token or OAuth grant. See Anthropic's [terms](https://www.anthropic.com/legal/consumer-terms) and [privacy policy](https://www.anthropic.com/legal/privacy). --- ## OAuth flow ``` Claude.ai Your WordPress Site │ │ │──GET /.well-known/oauth-protected-resource──▶│ │◀─── { authorization_servers: [...] } ────────│ │ │ │──GET /.well-known/oauth-authorization-server─▶│ │◀─── { authorization_endpoint, token_endpoint, registration_endpoint } ──│ │ │ │──POST /zen-mcp/v1/oauth/register──▶│ (RFC 7591 Dynamic Client Registration) │◀─── { client_id } ────────────│ │ │ │──GET /zen-mcp/v1/oauth/authorize──▶│ (PKCE code_challenge S256) │◀─── redirect to WP login ─────│ │ │ [User logs in as WP admin, clicks "Allow Access"] │ │ │◀─── redirect with ?code= ─────│ │ │ │──POST /zen-mcp/v1/oauth/token─────▶│ (code + code_verifier) │◀─── { access_token, expires_in } ───────────│ │ │ │──POST /zen-mcp/v1/bridge──────────▶│ (Authorization: Bearer <token>) │◀─── MCP JSON-RPC response ────│ ``` --- ## Troubleshooting ### 404 / `rest_no_route` 1. Go to **Settings → Permalinks** and click **Save Changes** to flush rewrite rules. 2. Confirm the plugin is active. 3. Test the endpoint manually: ```bash curl -s -X POST https://your-site.com/wp-json/zen-mcp/v1/bridge -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{}}}' ``` A working response starts with `{"jsonrpc":"2.0","id":1,"result":{...` ### The connector worked before 3.0.0 and now fails The 3.0.0 rename changed the REST namespace to `zen-mcp/v1`, so the endpoint URL is now `…/wp-json/zen-mcp/v1/bridge`. Reconnect and re-authenticate your Claude.ai connector. Your Bearer token, redirect URIs and token lifetime are preserved by a one-time migration. ### Authorization header always empty (Apache + FastCGI) Handled automatically since 2.4.0. If you still see issues, add to `.htaccess`: ```apache RewriteRule ^ - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}] ``` ### Enable debug logging Add to `wp-config.php`: ```php define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); define('WP_DEBUG_DISPLAY', false); ``` Then check `wp-content/debug.log`, or read it with the `wp_get_logs` tool. --- ## Changelog ### 3.2.3 Fixed a `BIGINT UNSIGNED` underflow in audit-log pruning, and corrected the reported Abilities count. ### 3.2.2 **Replaced free-form SQL with a structured query.** The `wp_db_query` tool previously executed a caller-supplied `SELECT`. Free-form SQL cannot be `prepare()`d — the whole string is the input — and exposing arbitrary database reads over a remote, token-authenticated endpoint is not acceptable regardless of the guards layered on top. The tool now assembles the query itself: identifiers are whitelisted against the live schema, values are bound. Single-table filtered reads only, and no injection surface. ### 3.2.1 Added `X-Content-Type-Options: nosniff` to all plugin responses. Replaced the use of WordPress auth salts for client identifiers with a dedicated plugin secret. The OAuth consent page's styles are now registered and printed by handle rather than emitted inline. Documented the external service in the readme. ### 3.0.0 **Renamed** — "WordPress MCP Bridge" → **Zen MCP Bridge** (slug `zen-mcp-bridge`, text domain, and REST namespace `zen-mcp/v1`). Existing installs keep their Bearer token, redirect URIs and token lifetime via a one-time migration on activation. **Breaking:** the MCP endpoint URL changed — reconnect your Claude.ai connector. Also: the settings page was rebuilt to the Zen family theme with setup and troubleshooting moved into a Help tab, and the plugin gained `readme.txt`, `uninstall.php`, internationalization, and input-sanitization fixes for WordPress.org. ### 2.8.0 Configurable OAuth token lifetime (1 hour, 24 hours, 7 days, 30 days) and a "Revoke All OAuth Tokens" button. MCP protocol version `2025-11-25` is now the highest supported — Claude.ai's version was previously always downgraded. Added `client_id_metadata_document_supported` to the authorization server metadata, `scope` to the `WWW-Authenticate` 401 header, and `description` to `serverInfo`. Consent-page expiry now reads "24 hours" rather than "1440 minutes". ### 2.7.0 Fixed SQL injection in the schema tool (`esc_like()` was used without `prepare()`); the OAuth consent nonce is sanitized with `sanitize_key()`. ### 2.6.0 Fixed `rest_cookie_invalid_nonce` 403 on "Allow Access" with a two-nonce form. Fixed `wp_get_options` being able to expose the plugin's own Bearer token. Fixed a cron-tool crash on PHP 8.2+ and cleaned up transients on deactivation. ### 2.5.0 Added the missing `registration_endpoint` (Claude Code could not connect). Corrected the declared PHP requirement to 8.0. Fixed a path containment guard that could be bypassed when `realpath()` returned `false`, and stopped valid empty-string OAuth parameters being stripped. ### 2.4.0 Fixed a double-firing `rest_api_init` inside a tool callback, a path prefix check bypassable by sibling directories, N+1 queries in the users tool, an unescaped output in the consent page, missing clickjacking protection on the consent page, and the Authorization header being stripped on Apache/FastCGI. ### 2.3.0 Fixed `wp_safe_redirect()` blocking OAuth code delivery to claude.ai, a PHP 8 `TypeError` on null JSON params, a log-path traversal via `ini_get('error_log')`, and token-endpoint responses always returning HTTP 200 even on errors. ### 2.2.0 Full OAuth 2.1 PKCE authorization server, with RFC 8414 and RFC 9728 discovery documents and old-spec `/authorize` + `/token` fallbacks. ### 2.1.0 Fixed the missing GET handler, OPTIONS preflight being blocked by the auth callback, missing CORS headers, an always-`1` post count, a missing `wp_reset_postdata()`, the API key autoloading, a spoofable rate-limit key, and inline `onclick` JS. --- ## Reporting a bug Open an issue on this repository. Please include: - WordPress version - PHP version - The exact error message or HTTP response - Output of `curl` against the MCP endpoint, with the token redacted --- ## About this repository This repository hosts the **documentation and project page** for Zen MCP Bridge. The plugin source is developed privately; the released, installable plugin is distributed through the [WordPress plugin directory](https://wordpress.org/plugins/zen-mcp-bridge/) under the GPL-2.0-or-later licence, which includes its complete source. Other plugins in the Zen family: - [Zen Site Security](https://github.com/guramzhgamadze/zen-site-security) — HTTPS, headers and hardening - [Zen Login & Authentication](https://github.com/guramzhgamadze/zen-login-authentication) — identity and two-factor auth - [Zen GEO](https://github.com/guramzhgamadze/zen-geo) — generative engine optimization - [Zen Blogger](https://github.com/guramzhgamadze/zen-blogger) — accessible Elementor blog widgets --- Built by [Guram Zhgamadze](https://github.com/guramzhgamadze).