WordPress MCP Server Integration: Complete Setup Guide

Leave a Comment / By

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. /Users/chrislee/.claude/wp-sites-config.json (WordPress Credentials)

This file contains WordPress site credentials and connection information.

{
  "adventuretube": {
    "URL": "https://adventuretube.net",
    "USER": "admin",
    "PASS": "xxxx xxxx xxxx xxxx xxxx xxxx"
  }
}

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. /Users/chrislee/extended-wordpress-mcp-server.js (MCP Server Implementation)

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

What it does:

  • Reads credentials from wp-sites-config.json
  • 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:

  • test_connection – Test WordPress API connection
  • create_post – Create new WordPress post
  • update_post – Update existing post
  • get_post – Retrieve post by ID
  • list_posts – List posts with pagination
  • 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)    │
└─────────────┘    └──────────────────────────────┘    └─────────────────────┘    └──────────────────────┘

Key Components

1. Claude Code (MCP Client)

  • User interface where commands are issued
  • Calls WordPress tools using MCP protocol
  • Displays results to user

2. extended-wordpress-mcp-server.js (Translation Layer)

  • MCP protocol ↔ WordPress REST API bridge
  • Speaks MCP protocol with Claude Code (stdio transport)
  • Speaks HTTP/REST with WordPress
  • Handles authentication (Basic Auth with application password)
  • Translates tool parameters to WordPress API format

3. WordPress REST API

  • Standard WordPress endpoints at /wp-json
  • Handles CRUD operations for posts, pages, media, etc.
  • Validates credentials and permissions
  • Returns structured JSON responses

4. WordPress Database

  • Actual data storage (MySQL/MariaDB)
  • Stores posts, users, metadata, etc.
  • Modified through WordPress REST API

How a Request Flows

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

Troubleshooting: Common Integration Issues

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

Timeline: First attempt at WordPress MCP integration

What Was Tried:

  • ❌ Installed Automattic’s WordPress MCP plugin on adventuretube.net
  • ❌ Enabled MCP functionality in WordPress Settings > MCP Settings
  • ❌ Configured Claude Code with HTTP transport to connect directly
  • ❌ Set up as project-level MCP server

The attempted architecture:

Claude Code → HTTP Transport → WordPress MCP Plugin → WordPress
                                        ❌ FAILED

Why It Failed:

  1. Missing Required Proxy: The WordPress MCP plugin requires a companion tool called mcp-wordpress-remote (a proxy server) to function. The plugin cannot operate standalone – it only works when the proxy is running and connected.

    What should have been:

    Claude Code → SSE → mcp-wordpress-remote (proxy) → WordPress Plugin → WordPress
                           ⚠️ THIS WAS MISSING
  2. Protocol Mismatch: Plugin expects SSE (Server-Sent Events) streaming protocol, but Claude Code provided HTTP request/response. Incompatible communication patterns.
  3. Architecture Incompatibility: WordPress MCP Plugin was designed for SSE-capable clients with proxy middleware, but Claude Code uses stdio transport for local custom servers.

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

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

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 than multi-layer plugin architecture

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

Timeline: After switching to custom MCP server and migrating from project to user scope

Context

  • ✅ Successfully implemented extended-wordpress-mcp-server.js (custom stdio MCP server)
  • ✅ Working in project scope initially
  • 🔄 Decided to migrate from project scope to user scope for cross-project availability
  • 🔄 Configuration moved to ~/.claude.json

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
  }
}

The Problem

WordPress MCP server failed to connect with error:

✘ failed · Failed to reconnect to wordpress-mcp

Root Cause

Relative paths don’t work in user-scoped MCP servers because:

  1. Claude Code’s working directory varies depending on which project you’re in
  2. extended-wordpress-mcp-server.js looked for the file relative to current project directory (e.g., /Volumes/Programming HD/AdventureTube/iOS/AdventureTube/)
  3. ./wp-sites-config.json couldn’t be found because it was actually in ~/.claude/ directory
  4. Server failed to start → connection failed

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
  }
}

What Changed

  1. Server file path: extended-wordpress-mcp-server.js → /Users/chrislee/extended-wordpress-mcp-server.js
  2. Config file path: ./wp-sites-config.json → /Users/chrislee/.claude/wp-sites-config.json

Verification

After updating to absolute paths, verify connection:

# Run in Claude Code
/mcp

Expected output:

✔ wordpress-mcp - connected

Key Lesson

Always use absolute paths for user-scoped MCP servers

  • ✅ Absolute paths: Work regardless of current directory
  • ❌ Relative paths: Only work in project-scoped configurations
  • 🎯 User-scoped servers must be location-agnostic

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

Required Files

  1. /Users/chrislee/extended-wordpress-mcp-server.js – MCP server implementation
  2. /Users/chrislee/.claude/wp-sites-config.json – WordPress credentials
  3. ~/.claude.json – MCP configuration with absolute paths

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)

Additional Best Practices:

  • Test connection with /mcp command after configuration changes
  • Keep credentials in separate config file (not in main ~/.claude.json)
  • Use WordPress Application Passwords (not regular passwords)
  • Verify HTTPS for WordPress site (required for Basic Auth security)

Security Notes

  • ✅ Uses WordPress Application Passwords (not regular passwords)
  • ✅ Basic Authentication over HTTPS
  • ✅ Credentials stored locally in config file
  • ✅ User-level installation (available across all projects)
  • ⚠️ Config file contains sensitive credentials – keep it secure

Related Posts

Leave a Comment

Your email address will not be published. Required fields are marked *