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

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

Tool	Description
wp-list-sites	List all configured WordPress sites, optionally filtered by tag
wp-site-status	Check the health/reachability of a single WordPress site
wp-fleet-status	Check the health of all configured sites (or those matching a tag)
wp-list-posts	List posts on a WordPress site
wp-create-post	Create a new post on a WordPress site
wp-update-post	Update an existing post on a WordPress site
wp-delete-post	Delete a post on a WordPress site
wp-list-pages	List pages on a WordPress site
wp-create-page	Create a new page on a WordPress site
wp-update-page	Update an existing page on a WordPress site
wp-delete-page	Delete a page on a WordPress site
wp-list-media	List media items on a WordPress site
wp-update-media	Update a media item on a WordPress site
wp-list-comments	List comments on a WordPress site
wp-update-comment	Update a comment on a WordPress site
wp-delete-comment	Delete a comment on a WordPress site
wp-list-categories	List categories on a WordPress site
wp-create-category	Create a new category on a WordPress site
wp-list-tags	List tags on a WordPress site
wp-create-tag	Create a new tag on a WordPress site
wp-list-users	List users on a WordPress site
wp-list-plugins	List installed plugins on a WordPress site
wp-get-settings	Get WordPress site settings
wp-bulk-execute	Execute a tool across multiple sites (filtered by tag)

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