# 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](https://modelcontextprotocol.io/) 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

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

For development (includes test dependencies):

```bash
pip install -e ".[dev]"
```

## Configuration

### 1. Site Configuration

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

```bash
cp config/sites.json.example config/sites.json
```

```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:

```bash
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`:

```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:

```json
{
  "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):

```bash
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](LICENSE).

## Author

**Roland Dalaguit** -- [github.com/ad02](https://github.com/ad02)