WordPress MCP Server

A Model Context Protocol (MCP) server that bridges AI assistants to WordPress, enabling natural-language management of posts, pages, media, comments, users, plugins, and settings across multiple sites simultaneously.

What is MCP?

The Model Context Protocol is an open standard that lets AI clients (like Claude Desktop and Claude Code) interact with external tools and data sources through a unified interface. This server implements MCP to expose WordPress REST API operations as callable tools, so an AI assistant can manage your WordPress sites through conversation.

AI Client (Claude)  --MCP-->  WordPress MCP Server  --REST API-->  WordPress Sites

Related MCP server: wp-mcp

Features

• 23 tools covering the full WordPress content lifecycle

• Multi-site support -- manage multiple WordPress installations from a single server

• Tag-based filtering -- organize sites by tag and run operations against groups

• Bulk execution -- execute any tool across multiple sites in one call

• Fleet health monitoring -- check reachability and status of all configured sites

• Async architecture -- built on Python's asyncio for non-blocking API calls

• Structured logging -- SQLite-backed request/response logging for auditability

Available Tools

Tech Stack

• Python 3.10+

• MCP SDK (mcp) -- Model Context Protocol framework

• httpx -- async HTTP client for WordPress REST API calls

• aiosqlite -- async SQLite for structured logging

• python-dotenv -- environment-based credential management

• pytest / pytest-asyncio / respx -- testing with async support and HTTP mocking

Installation

git clone https://github.com/ad02/WP-MCP-project.git
cd WP-MCP-project
pip install -e .

For development (includes test dependencies):

pip install -e ".[dev]"

Configuration

1. Site Configuration

Copy the example and edit it to register your WordPress sites:

cp config/sites.json.example config/sites.json

{
  "sites": [
    {
      "id": "my-site",
      "name": "My WordPress Site",
      "url": "https://example.com",
      "username": "mcp-agent",
      "app_password_env": "SITE_MY_SITE_APP_PASSWORD",
      "tags": ["production"],
      "enabled": true
    }
  ]
}

2. Credentials

Copy the example environment file and add your WordPress Application Passwords:

cp config/.env.example config/.env

Then edit config/.env:

SITE_MY_SITE_APP_PASSWORD=abcd efgh ijkl mnop qrst uvwx

Note: Application Passwords require WordPress 5.6+ and HTTPS. Generate them from Users > Profile > Application Passwords in the WordPress admin dashboard.

3. Connect to Claude

Claude Desktop -- add to your claude_desktop_config.json:

{
  "mcpServers": {
    "wp-mcp-hub": {
      "command": "python",
      "args": ["-m", "src"],
      "cwd": "/path/to/WP-MCP-project"
    }
  }
}

Claude Code -- add to your .claude/settings.json or project config:

{
  "mcpServers": {
    "wp-mcp-hub": {
      "command": "python",
      "args": ["-m", "src"],
      "cwd": "/path/to/WP-MCP-project"
    }
  }
}

Usage

Once connected, your AI client can call any of the 23 tools through natural conversation:

• "List all posts on my-site" -- calls wp-list-posts

• "Create a draft post titled 'Hello World' on my-site" -- calls wp-create-post

• "Check the status of all production sites" -- calls wp-fleet-status with tag filter

• "Delete comment 42 on my-site" -- calls wp-delete-comment

• "Run wp-list-plugins across all sites tagged 'production'" -- calls wp-bulk-execute

Testing

The test suite uses pytest with async support and HTTP response mocking (respx):

pytest -v

Tests cover configuration loading, WordPress API client behavior, tool registration, connection handling, batch execution, and structured logging.

Project Structure

WP-MCP-project/
├── src/
│   ├── __init__.py
│   ├── server.py        # MCP server entry point
│   ├── tools.py         # 23 tool definitions and handlers
│   ├── wp_client.py     # Async WordPress REST API client
│   ├── config.py        # Site configuration loader
│   ├── connection.py    # Connection/health checking
│   ├── batch.py         # Multi-site bulk execution
│   └── logger.py        # SQLite-backed structured logging
├── config/
│   ├── .env.example         # Template for credentials
│   └── sites.json.example   # Template for site registry
├── tests/               # pytest test suite
├── pyproject.toml
└── README.md

License

This project is licensed under the MIT License.

Author

Roland Dalaguit -- github.com/ad02