Which integrations are available for this server?

Provides pre-commit workflow integration for checking staged PHP files, auto-fixing violations, and re-staging files before commits, with the ability to block commits when coding standard errors are found. Enables automatic WordPress Coding Standards (WPCS) validation and auto-fixing for WordPress plugins and themes, including pre-commit checks, individual file/directory scanning, and integration with WordPress coding standards rulesets (WordPress-Core, WordPress-Extra, WordPress-Docs).

How do I use WPCS MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@WPCS MCP Server check my plugin's main PHP file for WPCS violations" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Write your WordPress plugin/theme code
Stage your changes: git add .
Ask Claude: "Run wpcs_pre_commit"
Claude will:
- Auto-fix what can be fixed (spacing, formatting, etc.)
- Re-stage the fixed files
- Report any remaining issues that need manual fixes
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:

PHP version is too old (need 8.2+)
Composer version is too old (need 2.0+)
Network issues

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

MCP server not loading in Claude Desktop

Verify the path in your config uses absolute paths (no ~)
Ensure you ran npm run build
Restart Claude Desktop completely (quit and reopen)
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.