WP MCP Audit

Remote WordPress/WooCommerce diagnostics and fixes via MCP (Model Context Protocol). No SSH required.

AI Client (Claude Desktop / Cursor)
    |  MCP Protocol (stdio)
    |
MCP Server (Node.js)
    |  HTTPS REST API (Basic Auth)
    |
WordPress Plugin
    |  Runs checks, reads files, queries DB, applies fixes
    |
Client's WordPress Site

Install the WordPress plugin on client sites. Connect through the MCP server from any AI client. Run diagnostics, read plugin/theme source code, query the database, and apply fixes -- all conversationally.

Quick Start

1. Install the WordPress Plugin

Upload wp-mcp-audit/ to your client's wp-content/plugins/ directory and activate it.

Requirements: PHP 7.4+, WordPress 5.8+

The plugin creates an "Auditor" role and registers custom capabilities on activation. Administrators get all capabilities automatically.

2. Create an Application Password

In the client's WordPress admin, go to Users > Profile > Application Passwords. Create a password for API access.

3. Configure the MCP Server

Create ~/.wp-audit/sites.json:

{
  "sites": [
    {
      "id": "client-acme",
      "label": "ACME Corp Website",
      "url": "https://acme.example.com",
      "username": "audit-user",
      "application_password": "xxxx xxxx xxxx xxxx",
      "features": ["woocommerce"]
    }
  ]
}

4. Add to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "wp-audit": {
      "command": "npx",
      "args": ["-y", "mcp-server-wp-audit"],
      "env": {
        "WP_AUDIT_SITES_CONFIG": "~/.wp-audit/sites.json"
      }
    }
  }
}

Or run from a local build:

{
  "mcpServers": {
    "wp-audit": {
      "command": "node",
      "args": ["/path/to/mcp-server-wp-audit/dist/bin/wp-audit-mcp.js"],
      "env": {
        "WP_AUDIT_SITES_CONFIG": "~/.wp-audit/sites.json"
      }
    }
  }
}

5. Start Auditing

In Claude Desktop, try:

"Run a full diagnostic on client-acme"

"What critical issues does client-acme have?"

"Clean up expired transients on client-acme"

"Read the main plugin file of woocommerce and check for any issues"

"Show me the wp_options rows related to caching"

"Patch the functions.php in my child theme to fix the broken filter"

Project Structure

wordpress-mcp-audit/
├── wp-mcp-audit/                 # WordPress Plugin (PHP)
│   ├── wp-mcp-audit.php          # Plugin bootstrap
│   ├── uninstall.php             # Cleanup on uninstall
│   ├── includes/
│   │   ├── class-autoloader.php  # PSR-4 autoloader (no Composer needed)
│   │   └── class-plugin.php      # Plugin singleton
│   └── src/
│       ├── Api/                  # REST controllers (6 files)
│       ├── Checks/               # 48 diagnostic checks (9 categories)
│       ├── Fixes/                # 12 fix classes
│       ├── Security/             # API keys, rate limiter, audit log
│       ├── Admin/                # WP admin settings pages
│       ├── Abilities/            # Roles & capabilities
│       └── Registry/             # Check & fix registries
│
└── mcp-server-wp-audit/          # MCP Server (Node.js/TypeScript)
    ├── bin/wp-audit-mcp.ts       # CLI entry point
    └── src/
        ├── index.ts              # Server init, tool registration
        ├── config/               # Multi-site config, types
        ├── client/               # REST API client
        ├── tools/                # 30 MCP tools
        ├── resources/            # Known conflicts, recommended settings
        └── prompts/              # Guided audit workflow

REST API Endpoints

Namespace: wp-mcp-audit/v1

Diagnostics & Site Info

Method	Endpoint	Permission	Description
GET	`/diagnostics`	`read`	Run all 48 checks
GET	`/diagnostics/summary`	`read`	Severity counts
GET	`/diagnostics/{category}`	`read`	Run checks for one category
GET	`/diagnostics/{category}/{check_id}`	`read`	Run a single check
GET	`/site-info`	`read`	WordPress site overview
GET	`/site-info/environment`	`read`	Server environment

Fixes

Method	Endpoint	Permission	Description
GET	`/fixes`	`fix_safe`	List available fixes
POST	`/fixes/{fix_id}/preview`	`fix_safe`	Dry-run a fix
POST	`/fixes/{fix_id}/apply`	`fix_safe`*	Apply a fix
POST	`/fixes/{fix_id}/rollback`	`fix_safe`	Rollback a fix

*Risky fixes require wp_mcp_audit_fix_risky.

File Access

Method	Endpoint	Permission	Description
GET	`/files/plugins`	`read`	List installed plugins
GET	`/files/themes`	`read`	List installed themes
GET	`/files/plugins/{slug}`	`read`	List files in a plugin
GET	`/files/themes/{slug}`	`read`	List files in a theme
POST	`/files/read`	`read`	Read a plugin/theme file
POST	`/files/write`	`fix_risky`	Write a file (with backup)
POST	`/files/patch`	`fix_risky`	Search-and-replace in a file (with backup)
POST	`/files/rollback`	`fix_risky`	Restore a file from backup

Database

Method	Endpoint	Permission	Description
GET	`/database/tables`	`read`	List all tables with sizes
GET	`/database/tables/{table}/schema`	`read`	Show table columns and indexes
GET	`/database/tables/{table}/sample`	`read`	Preview rows from a table
POST	`/database/query`	`manage`	Run a read-only SQL query (SELECT only)
POST	`/database/execute`	`fix_risky`	Run a write SQL query (INSERT/UPDATE/DELETE)
POST	`/database/options/get`	`read`	Read specific WP options
POST	`/database/options/search`	`read`	Search options by name pattern

All permissions are prefixed with wp_mcp_audit_ (e.g., read = wp_mcp_audit_read).

MCP Tools

30 tools available in the MCP server:

Diagnostics

Tool	Description
`run_diagnostics`	Run all checks on a site
`run_category_diagnostics`	Run checks for a specific category
`diagnostics_summary`	Get severity counts
`compare_diagnostics`	Compare diagnostics between two sites
`check_plugin_conflicts`	Check for known plugin conflicts

Fixes

Tool	Description
`list_fixes`	List available fixes
`preview_fix`	Dry-run a fix
`apply_fix`	Apply a fix (with confirmation for risky)
`rollback_fix`	Rollback a previously applied fix

Site Info

Tool	Description
`site_info`	WordPress site overview
`environment_info`	Server environment details
`check_recommended_settings`	Compare site against recommended settings

File Access

Tool	Description
`list_plugin_files`	List plugins or browse files in a plugin
`list_theme_files`	List themes or browse files in a theme
`read_file`	Read source code of a plugin or theme file
`write_file`	Write new contents to a file (with automatic backup)
`patch_file`	Search-and-replace in a file (safest way to make targeted edits)
`rollback_file`	Restore a file from a backup

Database

Tool	Description
`db_query`	Run a read-only SQL query (SELECT/SHOW/DESCRIBE)
`db_execute`	Run a write SQL query (INSERT/UPDATE/DELETE, requires confirmation)
`db_tables`	List all tables with sizes, or show schema for a specific table
`db_table_sample`	Preview rows from a database table
`db_options`	Read or search WordPress options

Multi-Site

Tool	Description
`list_sites`	List configured sites
`add_site`	Add a new site to config
`batch_diagnostics`	Run diagnostics across multiple sites

WooCommerce

Tool	Description
`wc_health`	WooCommerce health summary
`wc_order_issues`	WooCommerce order issues

Reporting

Tool	Description
`generate_report`	Generate a formatted audit report
`export_report`	Export report as JSON or markdown

Diagnostic Checks (48)

Category	Checks	What's Checked
Core	6	WP version, pending updates, cron health, debug settings, constants, filesystem
Plugins	5	Conflicts, outdated versions, vulnerabilities, known conflicts, inactive plugins
Themes	3	WP compatibility, parent theme, direct modifications
PHP	5	PHP version, error reporting, extensions, limits, error log
Database	5	Table integrity, sizes, orphaned data, autoload bloat, table engines
Server	5	Web server, SSL, .htaccess, disk space, memory
Security	6	File permissions, user enumeration, XML-RPC, login security, salts, wp-config
WooCommerce	8	Status, templates, gateways, shipping, API, DB version, scheduler, logs
Performance	5	Object cache, page cache, enqueued assets, query count, transients

Each check returns a standardized result:

{
  "id": "wp-version",
  "category": "core",
  "label": "WordPress Version",
  "status": "warning",
  "severity": 7,
  "description": "WordPress 6.4 is installed but 6.7 is available.",
  "details": { "current": "6.4.3", "latest": "6.7.1" },
  "fix": { "id": "manual-update", "type": "manual" },
  "timestamp": "2026-02-08T12:00:00+00:00"
}

Status values: good, warning, critical, info Severity: 1 (low) to 10 (critical)

Fixes (12)

Auto-fix (safe, reversible)

Fix	Description
`flush-cache`	Flush object cache, page cache, rewrite rules
`toggle-plugin`	Enable/disable a plugin
`update-option`	Safely update a WordPress option
`optimize-tables`	Run OPTIMIZE TABLE on database tables
`clean-transients`	Delete expired transients
`reschedule-cron`	Fix stuck/overdue cron events
`wc-recount`	WooCommerce: recount terms and order stats
`wc-clear-sessions`	Clear expired WooCommerce sessions

Manual (instructions only)

Fix	Description
`manual-update`	Step-by-step update instructions
`manual-server`	PHP upgrade, file permissions, SSL instructions

Risky (requires confirmation)

Fix	Description
`delete-inactive-plugins`	Delete inactive plugins from filesystem
`delete-orphaned-tables`	Delete orphaned database tables

All auto-fixes create backups in wp_options (prefix _wp_mcp_audit_backup_, 24-hour expiry) and support rollback.

Security

Authentication

WordPress Application Passwords (HTTPS Basic Auth) - primary auth method
Custom API keys via X-WP-Audit-Key header - optional, managed in WP admin

API keys are prefixed with wmca_, stored hashed via wp_hash_password(), and support granular permissions (read, fix_safe, fix_risky, manage).

Authorization

Custom capabilities with a dedicated "Auditor" role:

Capability	Description	Auditor Role
`wp_mcp_audit_read`	Run diagnostics, view site info	Yes
`wp_mcp_audit_fix_safe`	Apply auto-fixes	Yes
`wp_mcp_audit_fix_risky`	Apply risky fixes	No
`wp_mcp_audit_manage`	Manage API keys, settings	No

Administrators receive all four capabilities on plugin activation.

Rate Limiting

Transient-based, per API key or IP address:

Reads: 60 requests/minute (configurable)
Writes: 10 requests/minute (configurable)
Returns 429 Too Many Requests with Retry-After header when exceeded

Audit Logging

All API access is logged to a custom database table ({prefix}mcp_audit_log) with:

Timestamp, user ID, API key label
Endpoint, HTTP method, IP address
Request parameters, response status

Logs auto-clean after 30 days via WP-Cron (configurable in settings).

WP Admin Pages

After activation, find these under Tools in the WordPress admin:

WP MCP Audit - Enable/disable API, configure rate limits, set log retention
API Keys - Generate, view, and revoke API keys with per-key permissions

Development

MCP Server

cd mcp-server-wp-audit
npm install
npm run build    # Compile TypeScript
npm run dev      # Watch mode
npm start        # Run the server

Requires Node.js 18+.

WordPress Plugin

No build step required. The plugin includes its own PSR-4 autoloader and works without Composer on client sites.

For development with Composer autoloading:

cd wp-mcp-audit
composer install

Multi-Site Management

The MCP server supports managing multiple WordPress sites from a single config. Sites are stored in ~/.wp-audit/sites.json by default (configurable via WP_AUDIT_SITES_CONFIG env var).

{
  "sites": [
    {
      "id": "client-acme",
      "label": "ACME Corp Website",
      "url": "https://acme.example.com",
      "username": "audit-user",
      "application_password": "xxxx xxxx xxxx xxxx",
      "api_key": "wmca_optional_api_key",
      "features": ["woocommerce"]
    },
    {
      "id": "client-beta",
      "label": "Beta Store",
      "url": "https://beta.example.com",
      "username": "audit-user",
      "application_password": "yyyy yyyy yyyy yyyy",
      "features": ["woocommerce"]
    }
  ]
}

Use batch_diagnostics to run checks across all sites at once, or compare_diagnostics to compare two sites side by side.

Uninstall

When the plugin is deleted through WordPress admin, uninstall.php will:

Drop the {prefix}mcp_audit_log table
Delete all _wp_mcp_audit_* options (backups, settings, API keys)
Remove the Auditor role and all custom capabilities from all roles

License

WordPress Plugin: GPL-2.0-or-later
MCP Server: MIT

Built by OBS Technologies

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
mcp-server-wp-audit		mcp-server-wp-audit
wp-mcp-audit		wp-mcp-audit
.gitignore		.gitignore
.mcp.json		.mcp.json
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

WP MCP Audit

Quick Start

1. Install the WordPress Plugin

2. Create an Application Password

3. Configure the MCP Server

4. Add to Claude Desktop

5. Start Auditing

Project Structure

REST API Endpoints

Diagnostics & Site Info

Fixes

File Access

Database

MCP Tools

Diagnostics

Fixes

Site Info

File Access

Database

Multi-Site

WooCommerce

Reporting

Diagnostic Checks (48)

Fixes (12)

Auto-fix (safe, reversible)

Manual (instructions only)

Risky (requires confirmation)

Security

Authentication

Authorization

Rate Limiting

Audit Logging

WP Admin Pages

Development

MCP Server

WordPress Plugin

Multi-Site Management

Uninstall

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages