WPCS MCP Server

A Model Context Protocol (MCP) server that integrates WordPress Coding Standards (WPCS) with Claude AI. Automatically check and fix your WordPress plugin/theme code to meet WordPress.org standards.

Don't use Claude AI? No problem! See GIT-HOOKS-SETUP.md for standalone Git hooks, GitHub Actions, and CI/CD setup.

One-Line Install (Git Hooks Only)

For automatic WPCS checks on every commit without Claude AI:

curl -sSL https://raw.githubusercontent.com/vapvarun/wpcs-mcp-server/main/scripts/install-hooks.sh | bash

This installs phpcs + WPCS + PHPCompatibility and sets up pre-commit hooks in your current repo.

---

Why Use This?

If you're developing WordPress plugins or themes, your code must follow WordPress Coding Standards to:

• ✅ Get approved on WordPress.org plugin/theme directory
• ✅ Write consistent, readable code
• ✅ Follow security best practices
• ✅ Make your code maintainable

This MCP server lets Claude AI automatically check and fix your PHP code against WPCS before you commit.

---

Requirements Checklist

Before installing, ensure you have all requirements:

Requirement	Minimum Version	Check Command	Install Guide
Node.js	18+	node -v	nodejs.org
PHP	8.2+	php -v	See PHP Setup below
Composer	2.0+	composer -V	getcomposer.org
Claude Desktop or Claude Code	Latest	claude --version	claude.ai

PHP Setup by Platform

# Herd installs PHP at:
# ~/Library/Application Support/Herd/bin/php

# Verify Herd PHP
~/Library/Application\ Support/Herd/bin/php -v
# Should show PHP 8.2+

# Herd also provides Composer at:
# ~/Library/Application Support/Herd/bin/composer

# Install PHP 8.4
brew install php@8.4

# Add to PATH in ~/.zshrc
export PATH="/opt/homebrew/opt/php@8.4/bin:$PATH"

# Verify
php -v

# MAMP PHP location
/Applications/MAMP/bin/php/php8.2.x/bin/php

# Add to PATH in ~/.zshrc
export PATH="/Applications/MAMP/bin/php/php8.2.x/bin:$PATH"

# Install via Chocolatey
choco install php --version=8.4

# Or download from php.net and add to PATH

sudo apt update
sudo apt install php8.2 php8.2-cli composer

---

Quick Start

Step 1: Clone & Build

git clone https://github.com/vapvarun/wpcs-mcp-server.git ~/.mcp-servers/wpcs-mcp-server
cd ~/.mcp-servers/wpcs-mcp-server
npm install --include=dev && npm run build

Important: Use npm install --include=dev to ensure TypeScript compiler is available for building.

Step 2: Install WPCS Dependencies

The server attempts auto-install, but for reliability, install manually:

# Allow the composer installer plugin
composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

# Install phpcs, WPCS, and PHPCompatibility
composer global require squizlabs/php_codesniffer wp-coding-standards/wpcs phpcompatibility/phpcompatibility-wp dealerdirect/phpcodesniffer-composer-installer

# Verify installation
~/.composer/vendor/bin/phpcs -i
# Should show: WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra, PHPCompatibility, PHPCompatibilityWP

Step 3: Configure MCP Server

Choose your setup method:

---

Configuration Options

For Claude Code CLI (Recommended)

Option A: Using CLI Command (Global)

claude mcp add wpcs --scope user -- node ~/.mcp-servers/wpcs-mcp-server/build/index.js

Then manually add the PATH environment in ~/.claude.json:

{
  "mcpServers": {
    "wpcs": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.mcp-servers/wpcs-mcp-server/build/index.js"],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/Library/Application Support/Herd/bin:/Users/YOUR_USERNAME/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Option B: Manual Configuration (Global)

Add to ~/.claude.json under the mcpServers key at root level:

{
  "mcpServers": {
    "wpcs": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.mcp-servers/wpcs-mcp-server/build/index.js"],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/Library/Application Support/Herd/bin:/Users/YOUR_USERNAME/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Option C: Project-Level Configuration

Add to ~/.claude.json under a specific project:

{
  "projects": {
    "/path/to/your/wordpress-project": {
      "mcpServers": {
        "wpcs": {
          "type": "stdio",
          "command": "node",
          "args": ["/Users/YOUR_USERNAME/.mcp-servers/wpcs-mcp-server/build/index.js"],
          "env": {
            "PATH": "/Users/YOUR_USERNAME/Library/Application Support/Herd/bin:/Users/YOUR_USERNAME/.composer/vendor/bin:/usr/local/bin:/usr/bin:/bin"
          }
        }
      }
    }
  }
}

For Claude Desktop

macOS - Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "wpcs": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.mcp-servers/wpcs-mcp-server/build/index.js"],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/Library/Application Support/Herd/bin:/Users/YOUR_USERNAME/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Windows - Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "wpcs": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\.mcp-servers\\wpcs-mcp-server\\build\\index.js"],
      "env": {
        "PATH": "C:\\php;C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\Composer\\vendor\\bin;%PATH%"
      }
    }
  }
}

---

PATH Configuration by Setup

Choose the correct PATH based on your PHP installation:

PHP Setup	PATH Value
Herd (macOS)	~/Library/Application Support/Herd/bin:~/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin
Homebrew (macOS)	/opt/homebrew/opt/php@8.4/bin:~/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin
MAMP (macOS)	/Applications/MAMP/bin/php/php8.2.x/bin:~/.composer/vendor/bin:/usr/local/bin:/usr/bin:/bin
System PHP (Linux)	~/.composer/vendor/bin:/usr/local/bin:/usr/bin:/bin
Windows	C:\php;C:\Users\YOU\AppData\Roaming\Composer\vendor\bin

Important: Replace ~ with your full home path (e.g., /Users/yourname) in JSON configs.

---

Step 4: Verify Installation

# Check MCP server status
claude mcp list

# Should show:
# wpcs: node ~/.mcp-servers/wpcs-mcp-server/build/index.js - ✓ Connected

Test the Server Manually

cd ~/.mcp-servers/wpcs-mcp-server
PATH="YOUR_PHP_PATH:$HOME/.composer/vendor/bin:$PATH" node build/index.js

# Should output:
# Starting WPCS MCP Server...
# phpcs path: /Users/you/.composer/vendor/bin/phpcs
# Available standards: ... WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra, PHPCompatibility ...
# WPCS MCP Server running on stdio

---

Available Tools

Tool	What It Does
wpcs_pre_commit	Most useful! Auto-fix staged files, re-stage, report remaining issues
wpcs_check_staged	Check all staged PHP files before commit
wpcs_check_file	Check a single PHP file
wpcs_check_directory	Check all PHP files in a directory
wpcs_fix_file	Auto-fix WPCS violations in a file
wpcs_check_php_compatibility	Check PHP 8.1/8.2/8.3/8.4 compatibility

---

Usage Examples

Just ask Claude in natural language:

"Check my staged files for WPCS issues"
"Run wpcs_pre_commit before I commit"
"Fix WPCS issues in includes/class-my-plugin.php"
"Check the entire src/ directory for coding standards"
"Check PHP 8.2 compatibility for my plugin"
"Is my code compatible with PHP 8.1 to 8.4?"

Typical Workflow

1. Write your WordPress plugin/theme code
2. Stage your changes: git add .
3. Ask Claude: "Run wpcs_pre_commit"
4. Claude will:
   • Auto-fix what can be fixed (spacing, formatting, etc.)
   • Re-stage the fixed files
   • Report any remaining issues that need manual fixes
5. Commit your clean code!

---

What WPCS Checks

The WordPress ruleset includes:

Standard	What It Checks
WordPress-Core	Naming conventions, spacing, formatting, PHP compatibility
WordPress-Extra	Discouraged functions, loose comparisons, Yoda conditions
WordPress-Docs	PHPDoc comments, inline documentation

Common Issues It Catches:

• ❌ if($x == true) → ✅ if ( true === $x )
• ❌ Missing spaces in function calls
• ❌ Using extract(), eval(), create_function()
• ❌ Missing or incorrect PHPDoc blocks
• ❌ Incorrect text domain in translations
• ❌ Direct database queries without preparation

---

PHP Compatibility Checking

Check if your code works with PHP 8.1, 8.2, 8.3, and 8.4:

"Check PHP 8.2 compatibility for src/"
"Is my plugin compatible with PHP 8.1-8.4?"

What It Detects:

Issue Type	Example
Removed Functions	create_function() removed in PHP 8.0
Deprecated Features	${var} string interpolation deprecated in 8.2
New Syntax	Named arguments require PHP 8.0+
Type Changes	Return type changes in built-in functions
Removed Constants	FILTER_SANITIZE_STRING removed in 8.1

Version Examples:

"8.1"      → Check for PHP 8.1 compatibility only
"8.2"      → Check for PHP 8.2 compatibility only
"7.4-"     → Check PHP 7.4 and all newer versions
"8.1-8.4"  → Check PHP 8.1 through 8.4 compatibility

WordPress.org requires PHP 7.4+ minimum, so use "7.4-" to ensure broad compatibility.

---

Add Tool Permissions (Claude Code)

Add to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__wpcs__wpcs_check_staged",
      "mcp__wpcs__wpcs_check_file",
      "mcp__wpcs__wpcs_check_directory",
      "mcp__wpcs__wpcs_fix_file",
      "mcp__wpcs__wpcs_pre_commit",
      "mcp__wpcs__wpcs_check_php_compatibility"
    ]
  }
}

---

Optional: Auto-Check Before Commits

Add a Claude Code hook to automatically check WPCS before every commit.

Create ~/.claude/hooks/wpcs-pre-commit.sh:

#!/bin/bash
export PATH="$HOME/.composer/vendor/bin:$PATH"

STAGED_PHP=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.php$' || true)

if [ -z "$STAGED_PHP" ]; then
    exit 0
fi

PHP_COUNT=$(echo "$STAGED_PHP" | wc -l | tr -d ' ')
echo "WPCS: Found $PHP_COUNT staged PHP file(s). Run wpcs_pre_commit to check."
exit 0

Add to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$HOME/.claude/hooks/wpcs-pre-commit.sh\""
          }
        ]
      }
    ]
  }
}

---

Troubleshooting

"Failed to connect" in claude mcp list

Most common cause: Wrong PHP version in PATH.

# Check which PHP the MCP server sees
cd ~/.mcp-servers/wpcs-mcp-server
PATH="YOUR_CONFIG_PATH" node build/index.js 2>&1 | head -5

# If you see "PHP Fatal error: Composer detected issues... require PHP >= 8.2"
# Your PATH doesn't include PHP 8.2+

Fix: Update the PATH in your MCP config to include your PHP 8.2+ binary directory FIRST.

"phpcs not found"

# Install manually
composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require squizlabs/php_codesniffer wp-coding-standards/wpcs phpcompatibility/phpcompatibility-wp dealerdirect/phpcodesniffer-composer-installer

# Verify
~/.composer/vendor/bin/phpcs --version

"WordPress standard not found"

# Check available standards
~/.composer/vendor/bin/phpcs -i

# If WordPress not listed, reinstall:
composer global remove wp-coding-standards/wpcs dealerdirect/phpcodesniffer-composer-installer
composer global require wp-coding-standards/wpcs dealerdirect/phpcodesniffer-composer-installer

Build fails with "tsc: command not found"

cd ~/.mcp-servers/wpcs-mcp-server
rm -rf node_modules
npm install --include=dev
npm run build

"Auto-install failed" on server startup

This happens when:

1. PHP version is too old (need 8.2+)
2. Composer version is too old (need 2.0+)
3. Network issues

Fix: Install dependencies manually (see Step 2 above).

MCP server not loading in Claude Desktop

1. Verify the path in your config uses absolute paths (no ~)
2. Ensure you ran npm run build
3. Restart Claude Desktop completely (quit and reopen)
4. Check the path exists: ls -la ~/.mcp-servers/wpcs-mcp-server/build/index.js

---

Development

git clone https://github.com/vapvarun/wpcs-mcp-server.git
cd wpcs-mcp-server
npm install --include=dev
npm run build

# Watch mode for development
npm run dev

---

Complete Setup Checklist

Use this checklist to ensure everything is configured correctly:

• Node.js 18+ installed (node -v)
• PHP 8.2+ installed and in PATH (php -v)
• Composer 2.0+ installed (composer -V)
• Repository cloned to ~/.mcp-servers/wpcs-mcp-server
• Built with dev dependencies (npm install --include=dev && npm run build)
• WPCS installed globally via Composer
• phpcs shows WordPress standards (~/.composer/vendor/bin/phpcs -i)
• MCP config added to ~/.claude.json or Claude Desktop config
• PATH includes PHP binary directory in MCP env config
• PATH includes composer/vendor/bin in MCP env config
• Server shows Connected (claude mcp list)

---

License

GPL-2.0-or-later

Author

Varun Dubey (@vapvarun)

• Website: wbcomdesigns.com
• Email: varun@wbcomdesigns.com

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• WordPress Coding Standards
• PHP_CodeSniffer
• Model Context Protocol