Claude Code WordPress MCP Server Integration

Overview

This document explains how to integrate WordPress with Claude Code using a custom MCP (Model Context Protocol) server. The MCP server acts as a bridge between Claude Code and the WordPress REST API, enabling programmatic WordPress site management.

Configuration Files

The WordPress MCP integration requires three configuration files working together:

1. ~/.claude.json (MCP Server Configuration)

This is the main Claude Code configuration file that defines the WordPress MCP server.

"wordpress-mcp": {
  "command": "node",
  "args": [
    "/Users/chrislee/extended-wordpress-mcp-server.js"
  ],
  "env": {
    "WP_SITES_PATH": "/Users/chrislee/.claude/wp-sites-config.json"
  }
}

Key Points:

command: Specifies Node.js to run the server
args: Path to the MCP server JavaScript file (⚠️ must be absolute path for user-scoped servers)
env.WP_SITES_PATH: Path to WordPress credentials file (⚠️ must be absolute path)

2. WordPress Credentials Configuration

This file contains WordPress site credentials and connection information.

{
  "adventuretube": {
    "URL": "https://adventuretube.net",
    "USER": "your-email@example.com",
    "PASS": "your-application-password"
  }
}

Key Points:

adventuretube: Site alias (used when calling MCP tools)
URL: WordPress site URL
USER: WordPress username
PASS: WordPress Application Password (NOT regular password)

3. MCP Server Implementation (extended-wordpress-mcp-server.js)

This is the custom MCP server that handles communication between Claude Code and WordPress REST API.

What it does:

Reads credentials from config file
Implements MCP protocol to communicate with Claude Code
Translates MCP tool calls to WordPress REST API requests
Handles authentication with WordPress (Basic Auth)
Returns formatted responses to Claude Code

Available Tools:

mcp__wordpress__test_connection – Test WordPress API connection
mcp__wordpress__create_post – Create new WordPress post
mcp__wordpress__update_post – Update existing post
mcp__wordpress__get_post – Retrieve post by ID
mcp__wordpress__list_posts – List posts with pagination
mcp__wordpress__delete_post – Delete post (trash or permanent)
wp_discover_endpoints – Map available REST API endpoints
wp_call_endpoint – Execute custom REST API requests

Architecture: How It Works

Sequential Diagram

┌─────────────┐      ┌──────────────────────────────┐      ┌─────────────────────┐      ┌──────────────────────┐
│ Claude Code │      │ extended-wordpress-mcp-server │      │ WordPress REST API  │      │ WordPress Database   │
│   (Client)  │      │     (MCP Server/Gateway)      │      │  (adventuretube.net)│      │    (MySQL/MariaDB)   │
└──────┬──────┘      └──────────────┬───────────────┘      └──────────┬──────────┘      └──────────┬───────────┘
       │                            │                                  │                            │
       │  1. Call create_post       │                                  │                            │
       ├───────────────────────────▶│                                  │                            │
       │                            │  2. Read credentials             │                            │
       │                            │  3. POST /wp-json/wp/v2/posts    │                            │
       │                            ├─────────────────────────────────▶│                            │
       │                            │                                  │  4. Validate & INSERT      │
       │                            │                                  ├───────────────────────────▶│
       │                            │                                  │  5. Return post_id         │
       │                            │                                  │◀───────────────────────────┤
       │                            │  6. Response JSON                │                            │
       │                            │◀─────────────────────────────────┤                            │
       │  7. Formatted result       │                                  │                            │
       │◀───────────────────────────┤                                  │                            │

Key Components

Claude Code (MCP Client) – User interface where commands are issued
extended-wordpress-mcp-server.js (Translation Layer) – MCP protocol ↔ WordPress REST API bridge
WordPress REST API – Standard WordPress endpoints at /wp-json
WordPress Database – Actual data storage (MySQL/MariaDB)

How a Request Flows

Startup: Claude Code launches the server via Node.js
Tool Call: User asks Claude to create/update WordPress content
MCP Protocol: Claude Code sends MCP tool request to server
Credential Loading: Server reads site credentials from config file
API Translation: Server converts MCP parameters to WordPress REST API format
Authentication: Server adds Basic Auth headers
HTTP Request: Server sends POST/GET/PUT/DELETE to WordPress
WordPress Processing: WordPress validates, processes, updates database
Response: WordPress returns JSON response
MCP Format: Server formats response for Claude Code
Display: User sees result in Claude Code interface

Troubleshooting: Common Integration Issues

Issue #1: WordPress MCP Plugin Approach (Project Scope)

What Was Tried:

❌ Installed Automattic’s WordPress MCP plugin
❌ Enabled MCP functionality in WordPress Settings
❌ Configured Claude Code with HTTP transport to connect directly

Why It Failed:

Missing Required Proxy: The WordPress MCP plugin requires a companion tool called mcp-wordpress-remote (a proxy server) to function
Protocol Mismatch: Plugin expects SSE streaming protocol, but Claude Code provided HTTP request/response
Architecture Incompatibility: Plugin was designed for SSE-capable clients with proxy middleware

The Solution: Abandoned the plugin approach and built a custom stdio-based MCP server:

Claude Code → stdio → extended-wordpress-mcp-server.js → WordPress REST API ✅

Key Lessons:

Plugin ≠ Standalone Server: WordPress MCP plugin requires mcp-wordpress-remote proxy
Use stdio for Custom Servers: Claude Code works best with stdio transport for local servers
Direct API is Simpler: Custom stdio server with direct REST API calls is simpler and more reliable

Issue #2: Relative Path Configuration (User Scope Migration)

Initial Configuration (Broken):

"wordpress-mcp": {
  "command": "node",
  "args": [
    "extended-wordpress-mcp-server.js"  // ❌ Relative path
  ],
  "env": {
    "WP_SITES_PATH": "./wp-sites-config.json"  // ❌ Relative path
  }
}

Root Cause: Relative paths don’t work in user-scoped MCP servers because Claude Code’s working directory varies depending on which project you’re in.

Solution (Working Configuration):

"wordpress-mcp": {
  "command": "node",
  "args": [
    "/Users/chrislee/extended-wordpress-mcp-server.js"  // ✅ Absolute path
  ],
  "env": {
    "WP_SITES_PATH": "/Users/chrislee/.claude/wp-sites-config.json"  // ✅ Absolute path
  }
}

Always use absolute paths for user-scoped MCP servers
✅ Absolute paths: Work regardless of current directory
❌ Relative paths: Only work in project-scoped configurations

Summary: Working WordPress MCP Setup

Final Architecture

✅ Custom stdio MCP server (extended-wordpress-mcp-server.js)
✅ User-scoped installation (available across all projects)
✅ Absolute paths for all file references
✅ Direct WordPress REST API communication
✅ No plugin or proxy required

Configuration Best Practices

Scope	Path Type	Reason
User Scope	Absolute paths	Working directory varies by project
Project Scope	Relative paths OK	Working directory is predictable (project root)

Security Notes

✅ Uses WordPress Application Passwords (not regular passwords)
✅ Basic Authentication over HTTPS
✅ Credentials stored locally in config file
⚠️ Config file contains sensitive credentials – keep it secure