wp-diagnostics-mcp

An MCP server that gives an AI assistant direct diagnostic access to a local WordPress install — plugin, PHP, and environment info, debug-log tailing, a guarded read-only SQL query tool, and a pair of tools built specifically for Gravity Forms support work.

Built against a real Local by Flywheel WordPress site running the Gravity Forms / Gravity PDF stack, as a portfolio project pairing hands-on WordPress support experience with MCP server development.

Tools

Related MCP server: WordPress Developer MCP Server

Why it looks the way it does

Local by Flywheel doesn't put php or wp on PATH — each site is pinned to its own bundled PHP version, and WP-CLI ships as a single .phar inside the Local.app bundle. wp-config.php also sets DB_HOST to plain localhost, but Local runs each site's MySQL on its own per-site socket rather than the system default, so a bare CLI call fails with a database connection error even though WP-CLI itself is reachable.

server.py centralizes all of that into one run_wp_cli() helper that points the PHP binary, mysqli/pdo_mysql, and the mysql client (for wp db query, which shells out to it directly) at the correct per-site socket. Every tool above is a thin wrapper around a specific WP-CLI command.

Setup

Requires uv and a running Local by Flywheel site.

uv sync
cp local_config.example.py local_config.py

Fill in local_config.py with your own site's paths (PHP_BIN, WP_CLI_PHAR, SITE_PATH, DB_SOCKET, MYSQL_BIN_DIR) — see the comments in local_config.example.py for how to find each one. This file is gitignored since these paths are specific to one Local installation and site, not portable as-is.

Register it with an MCP client (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "wp-diagnostics": {
      "command": "uv",
      "args": ["--directory", "/path/to/wp-diagnostics-mcp", "run", "server.py"]
    }
  }
}

Scope

Local-only diagnostics for a single WordPress install. wp_db_query is intentionally read-only — it rejects any statement that isn't a single SELECT — since this is meant for inspection, not administration.