WordPress MCP Bridge

This bridge allows stdio-based MCP clients (like Cursor, Windsurf, Zed) to connect to the HTTP-based WordPress MCP server.

Why is this needed?

Code editors like Cursor and Windsurf expect MCP servers to communicate via stdio (standard input/output), but the WordPress MCP plugin uses HTTP/REST API. This bridge translates between the two protocols.

Installation

Prerequisites

• Node.js installed on your system
• WordPress MCP plugin activated
• Application Password created in WordPress
• curl installed (for URL-based method)

Setup Methods

There are two ways to use the bridge:

1. URL-based (Recommended) - Downloads the bridge script automatically from your WordPress site
2. File-based - Uses an absolute file path to the bridge script

Configuration

Method 1: URL-based Configuration (Recommended)

This method downloads the bridge script directly from your WordPress site, eliminating the need for absolute file paths.

Benefits:

• No need to specify absolute file paths
• Works across different machines without configuration changes
• Automatically uses the latest version of the bridge script
• Easier to share configurations with team members

For Windsurf (URL-based)

Edit your MCP config file at:

• Windows: %APPDATA%\.codeium\windsurf\mcp_config.json
• macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows Configuration:

{
  "mcpServers": {
    "wordpress": {
      "command": "cmd",
      "args": [
        "/c",
        "curl -k -s https://yoursite.com/wp-json/cws-mcp/v1/bridge | node - https://yoursite.com/wp-json/cws-mcp/v1/messages your-username \"your-app-password\""
      ],
      "disabled": false,
      "env": {}
    }
  }
}

macOS/Linux Configuration:

{
  "mcpServers": {
    "wordpress": {
      "command": "bash",
      "args": [
        "-c",
        "curl -k -s https://yoursite.com/wp-json/cws-mcp/v1/bridge | node - https://yoursite.com/wp-json/cws-mcp/v1/messages your-username \"your-app-password\""
      ],
      "disabled": false,
      "env": {}
    }
  }
}

For Cursor (URL-based)

Edit your MCP config file at:

• Windows: %USERPROFILE%\.cursor\mcp.json
• macOS/Linux: ~/.cursor/mcp.json

Use the same configuration format as Windsurf above.

Method 2: File-based Configuration

This method uses an absolute file path to the bridge script. Use this if you prefer not to download the script on each connection.

For Windsurf (File-based)

Edit your MCP config file at:

• Windows: %APPDATA%\.codeium\windsurf\mcp_config.json
• macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Configuration:

{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": [
        "/absolute/path/to/wordpress-mcp-bridge.js",
        "https://yoursite.com/wp-json/cws-mcp/v1/messages",
        "your-username",
        "your-app-password"
      ],
      "disabled": false,
      "env": {}
    }
  }
}

Windows Example:

{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": [
        "D:\\Projects\\WordPress\\mcp-test\\app\\public\\wp-content\\plugins\\cws-mcp\\bridge\\wordpress-mcp-bridge.js",
        "https://mcp-test.local/wp-json/cws-mcp/v1/messages",
        "admin",
        "aR0d Kg8v iVfp ZgFP 0e36 ntCB"
      ],
      "disabled": false,
      "env": {}
    }
  }
}

For Cursor (File-based)

Edit your MCP config file at:

• Windows: %USERPROFILE%\.cursor\mcp.json
• macOS/Linux: ~/.cursor/mcp.json

Use the same configuration format as Windsurf above.

For Zed

Edit your Zed settings:

• macOS: ~/.config/zed/settings.json
• Linux: ~/.config/zed/settings.json
• Windows: %APPDATA%\Zed\settings.json

Add:

{
  "context_servers": {
    "wordpress": {
      "command": {
        "path": "node",
        "args": [
          "/absolute/path/to/wordpress-mcp-bridge.js",
          "https://yoursite.com/wp-json/cws-mcp/v1/messages",
          "your-username",
          "your-app-password"
        ]
      }
    }
  }
}

Testing the Bridge

Manual Test

# Navigate to the bridge directory
cd /path/to/wp-content/plugins/cws-mcp/bridge

# Run the bridge manually
node wordpress-mcp-bridge.js https://yoursite.com/wp-json/cws-mcp/v1/messages admin "your-app-password"

# Type a JSON-RPC request (press Enter after):
{"jsonrpc":"2.0","method":"tools/list","id":1}

# You should see a response with available tools

Test with echo

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node wordpress-mcp-bridge.js https://yoursite.com/wp-json/cws-mcp/v1/messages admin "your-app-password"

Troubleshooting

Issue: "Cannot find module"

Solution: Make sure Node.js is installed and in your PATH.

node --version

Issue: "ECONNREFUSED" or connection errors

Solutions:

1. Verify WordPress site is accessible
2. Check the endpoint URL is correct
3. Test the endpoint directly:

   curl -X POST https://yoursite.com/wp-json/cws-mcp/v1/messages \
     -H "Content-Type: application/json" \
     -u "username:password" \
     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Issue: "401 Unauthorized"

Solutions:

1. Verify Application Password is correct
2. Check username is correct
3. Ensure Application Passwords are enabled in WordPress
4. Try creating a new Application Password

Issue: "UNABLE_TO_VERIFY_LEAF_SIGNATURE" (SSL errors)

The bridge automatically accepts self-signed certificates for local development. If you need to disable this in production:

Edit wordpress-mcp-bridge.js and remove this line:

process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

Issue: Bridge not showing in editor

Solutions:

1. Restart your code editor completely
2. Check the MCP config file syntax is valid JSON
3. Verify the absolute path to the bridge script is correct
4. Check editor logs for MCP errors

Viewing Bridge Logs

The bridge logs to stderr (not stdout, to avoid interfering with MCP communication).

To see logs:

node wordpress-mcp-bridge.js https://yoursite.com/wp-json/cws-mcp/v1/messages admin "password" 2> bridge.log

Then check bridge.log for error messages.

How It Works

1. Editor sends JSON-RPC request via stdin
2. Bridge receives request from stdin
3. Bridge forwards request to WordPress via HTTP POST
4. WordPress processes request and returns JSON-RPC response
5. Bridge sends response back to editor via stdout

┌─────────┐     stdio      ┌────────┐     HTTP      ┌───────────┐
│ Editor  │ ←────────────→ │ Bridge │ ←───────────→ │ WordPress │
│(Cursor) │   JSON-RPC     │(Node.js)│  JSON-RPC    │    MCP    │
└─────────┘                └────────┘               └───────────┘

Security Notes

1. Never commit your Application Password to version control
2. Use environment variables for sensitive data in production
3. The bridge accepts self-signed certificates for local development only
4. Application Passwords can be revoked at any time in WordPress

Alternative: Use Claude Desktop

If you prefer not to use the bridge, Claude Desktop natively supports HTTP-based MCP servers and works directly with the WordPress plugin without any bridge:

Claude Desktop config (~/.config/claude/config.json):

{
  "mcpServers": {
    "wordpress": {
      "url": "https://yoursite.com/wp-json/cws-mcp/v1/messages",
      "auth": {
        "type": "basic",
        "username": "your-username",
        "password": "your-app-password"
      }
    }
  }
}

Support

For issues with:

• The bridge: Check this README
• WordPress MCP plugin: See main plugin documentation
• Your code editor: Check editor's MCP documentation