WP Audit MCP Server

MCP (Model Context Protocol) server for comprehensive WordPress site audits on WP Engine.

What is This?

This is an MCP server that gives Claude Code specialized tools for auditing and optimizing WordPress sites hosted on WP Engine. Instead of manually running PHP scripts and API calls, you can simply ask Claude to audit a site and it will use these tools automatically.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│ Your Computer                                                   │
│                                                                 │
│  Claude Code ◄──stdio──► wp-audit-mcp (Node.js)                │
│                               │                                 │
│                               ├──SSH──► WP Engine sites         │
│                               │         (runs WP-CLI/PHP)       │
│                               │                                 │
│                               └──HTTPS──► CloudFlare API        │
└─────────────────────────────────────────────────────────────────┘

1. Claude Code starts the MCP server as a local subprocess
2. They communicate via stdin/stdout (not network)
3. When you ask Claude to audit a site, it calls the MCP tools
4. The MCP server connects to WP Engine via SSH and runs PHP scripts
5. For CloudFlare, it makes API calls directly

Features

Installation

Prerequisites

#### 1. Node.js 18+

Download from nodejs.org or use a version manager:

# Check your version
node --version  # Should be v18.x or higher

# macOS (with Homebrew)
brew install node

# Windows (with Chocolatey)
choco install nodejs

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

#### 2. Claude Code

Install Claude Code if you haven't:

npm install -g @anthropic-ai/claude-code

#### 3. SSH Access to WP Engine

You need SSH key-based authentication to WP Engine sites.

Generate an SSH key (if you don't have one):

ssh-keygen -t ed25519 -C "[email protected]"

Add your public key to WP Engine:

1. Log into WP Engine Portal
2. Go to My Profile → SSH Keys
3. Click Add SSH Key
4. Paste contents of ~/.ssh/id_ed25519.pub

Test the connection:

# Replace SITEID with your WP Engine environment name
ssh [email protected] 'echo "Connected successfully"'

#### 4. CloudFlare Global API Key (Optional)

Only needed if you want to use the CloudFlare tools.

1. Log into CloudFlare Dashboard
2. Click your profile icon → My Profile
3. Go to API Tokens tab
4. Find Global API Key → Click View
5. Copy the key (you'll need this when running CloudFlare tools)

Note: Use the Global API Key, not an API Token. The Global API Key works with all zones.

Step-by-Step Installation

#### Step 1: Clone the Repository

# Clone to a permanent location (not in a project folder)
git clone https://github.com/markahope-aag/wp-audit-mcp.git ~/wp-audit-mcp

# Or on Windows
git clone https://github.com/markahope-aag/wp-audit-mcp.git C:\tools\wp-audit-mcp

#### Step 2: Install Dependencies and Build

cd ~/wp-audit-mcp   # or C:\tools\wp-audit-mcp on Windows

# Install Node.js dependencies
npm install

# Build the TypeScript code
npm run build

You should see a dist/ folder created with the compiled JavaScript.

#### Step 3: Configure Claude Code

Claude Code uses a .mcp.json file to know about MCP servers. You need to add this server to that file.

Option A: Use the configure script

# Run from your project directory (where you use Claude Code)
~/wp-audit-mcp/configure.sh .

# Windows
C:\tools\wp-audit-mcp\configure.sh .

Option B: Manual configuration

Create or edit .mcp.json in your project directory:

{
  "mcpServers": {
    "wp-audit": {
      "command": "node",
      "args": ["/Users/yourname/wp-audit-mcp/dist/index.js"]
    }
  }
}

Important: Use the full absolute path to dist/index.js:

• macOS/Linux: /Users/yourname/wp-audit-mcp/dist/index.js
• Windows: C:/tools/wp-audit-mcp/dist/index.js (use forward slashes)

#### Step 4: Restart Claude Code

# Start Claude Code in your project directory
cd /path/to/your/project
claude

When Claude Code starts, it will automatically start the MCP server. You should see it connect without errors.

#### Step 5: Verify Installation

Ask Claude:

What MCP tools do you have available for WordPress audits?

Claude should list the wp_baseline, wp_cleanup, and other tools.

Configuration Details

The .mcp.json File

The .mcp.json file tells Claude Code which MCP servers to start. It can be placed in:

• Project directory (recommended) - Tools available for that project
• Home directory (~/.mcp.json) - Tools available globally

Example with multiple servers:

{
  "mcpServers": {
    "wp-audit": {
      "command": "node",
      "args": ["/Users/yourname/wp-audit-mcp/dist/index.js"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-memory"],
      "env": {
        "MEMORY_FILE_PATH": "./.claude/memory.json"
      }
    }
  }
}

How Tools Connect to WP Engine

The MCP server uses SSH to connect to WP Engine and run WP-CLI commands:

# This is what happens behind the scenes
ssh [email protected] 'wp eval-file /tmp/script.php'

The site_id parameter you provide is the WP Engine environment name, which you can find in:

• WP Engine Portal URL: my.wpengine.com/installs/SITEID
• Or in the site's "Overview" page

SSH Configuration (Optional)

For convenience, you can add WP Engine sites to ~/.ssh/config:

Host wpengine-mysite
    HostName mysite.ssh.wpengine.net
    User mysite
    IdentityFile ~/.ssh/id_ed25519

This doesn't affect how the MCP server works, but makes manual SSH easier.

Usage

Basic Commands

Once installed, just talk to Claude naturally:

Audit the WordPress site "mysite" on WP Engine

Or be more specific:

Use wp_baseline with site_id "mysite"

Example Session

You: I need to audit the site "clientsite" - check SEO, clean up the database,
     and fix CloudFlare settings. Zone ID is abc123def456.

Claude: I'll run a comprehensive audit. Let me start with the baseline...
        [Uses wp_baseline]

        Now checking SEO meta descriptions...
        [Uses wp_seo_check]

        I found 15 pages missing meta descriptions. Should I auto-generate them?

You: Yes, generate them.

Claude: [Uses wp_seo_fix with mode "auto"]
        Done. Now checking CloudFlare...
        [Uses cloudflare_check]

        Found issues: SSL is "flexible" (should be "full"), TLS 1.0 (should be 1.2).
        Should I fix these?

You: Yes, fix all CloudFlare issues.

Claude: [Uses cloudflare_fix]
        All CloudFlare settings updated. Let me clear all caches...
        [Uses wp_clear_cache]

        Audit complete! Here's the summary...

Tools Reference

wp_baseline

Run comprehensive baseline audit on a WordPress site.

Parameters:
  site_id: WP Engine environment name (required)

Returns: Content counts, database size, orphaned data, SEO status,
         WP Rocket settings, deleted plugin artifacts

wp_cleanup

Clean orphaned data and optimize database.

Parameters:
  site_id: WP Engine environment name (required)
  delete_revisions: Delete post revisions (default: true)

Actions: Removes orphaned postmeta, termmeta, commentmeta, auto-drafts,
         transients, old action scheduler entries. Closes pingbacks.

wp_plugin_artifacts

Remove database artifacts from deleted plugins.

Parameters:
  site_id: WP Engine environment name (required)
  plugins: Array of plugins to clean (optional - cleans all if empty)
           Options: yoast, rankmath, aioseo, wsal, revslider,
                    layerslider, woocommerce, jetpack
  dry_run: Preview changes without applying (default: false)

Actions: Drops orphaned tables, deletes leftover options

wp_seo_check

Check meta description status for pages/posts.

Parameters:
  site_id: WP Engine environment name (required)
  post_type: 'page', 'post', or 'all' (default: 'page')

Returns: Count of pages with/without meta descriptions, list of missing

wp_seo_fix

Add meta descriptions to content.

Parameters:
  site_id: WP Engine environment name (required)
  mode: 'auto' or 'manual' (default: 'auto')
  post_type: For auto mode (default: 'page')
  descriptions: For manual mode - {postId: "description"} object
  dry_run: Preview changes (default: false)

Auto mode: Extracts first 155 chars from page content
Manual mode: Sets specific descriptions for specific post IDs

wp_rocket_fix

Check and fix WP Rocket settings.

Parameters:
  site_id: WP Engine environment name (required)
  dry_run: Preview changes (default: false)

Fixes: Enables cache preload, sitemap preload, lazy loading, mobile cache

wp_clear_cache

Clear all caches on the site.

Parameters:
  site_id: WP Engine environment name (required)

Clears: WordPress object cache, transients, WP Rocket, WP Super Cache,
        Elementor, Beaver Builder, Divi, WP Engine page cache

cloudflare_check

Check CloudFlare security and performance settings.

Parameters:
  zone_id: CloudFlare Zone ID (required)
  email: CloudFlare account email (required)
  api_key: CloudFlare Global API Key (required)

Checks: SSL mode, min TLS version, HSTS, Bot Fight Mode,
        AI bot protection, crawler protection

cloudflare_fix

Apply recommended CloudFlare settings.

Parameters:
  zone_id: CloudFlare Zone ID (required)
  email: CloudFlare account email (required)
  api_key: CloudFlare Global API Key (required)
  fix_ssl: Fix SSL to 'full' (optional)
  fix_tls: Fix min TLS to 1.2 (optional)
  fix_hsts: Enable HSTS with 6-month max-age (optional)
  fix_bots: Enable bot protection (optional)
  fix_all: Apply all fixes (default: auto-detects what's needed)

ahrefs_extract

Extract and summarize an Ahrefs site audit ZIP file.

Parameters:
  zip_path: Full path to Ahrefs ZIP export (required)
  output_dir: Directory to extract to (optional)

Returns: Summary of errors, warnings, and notices from the audit

Typical Audit Workflow

1. Baseline: wp_baseline - Understand the site's current state
2. Ahrefs: ahrefs_extract - Parse Ahrefs audit file if provided
3. CloudFlare: cloudflare_check → cloudflare_fix - Fix security settings
4. Database: wp_cleanup → wp_plugin_artifacts - Clean up database
5. SEO: wp_seo_check → wp_seo_fix - Fix missing meta descriptions
6. Caching: wp_rocket_fix - Optimize WP Rocket
7. Finish: wp_clear_cache - Clear all caches

Troubleshooting

"SSH connection failed"

1. Verify SSH key is added to WP Engine Portal
2. Test manually: ssh [email protected] 'echo test'
3. Check that site_id matches the WP Engine environment name exactly

"MCP server not found"

1. Verify the path in .mcp.json is absolute and correct
2. Check that npm run build completed without errors
3. Verify dist/index.js exists

"CloudFlare authentication failed"

1. Use the Global API Key, not an API Token
2. Verify the email matches your CloudFlare login
3. Check the Zone ID is correct (found in CloudFlare dashboard overview)

Tools not appearing in Claude

1. Restart Claude Code completely
2. Check .mcp.json is in the current directory
3. Look for errors when Claude Code starts

Supported Platforms

• Windows - Via Git Bash, WSL, or native (with forward slashes in paths)
• macOS - Native terminal
• Linux - Native terminal

Development

# Run in development mode (watches for changes)
npm run dev

# Build for production
npm run build

# The server communicates via stdio, so to test manually:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

License

MIT

Contributing

Issues and pull requests welcome at github.com/markahope-aag/wp-audit-mcp.