# WordPress MCP Server

A TypeScript [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for managing WordPress sites via the REST API. Supports any WordPress 5.6+ site, including sites using the Divi theme.

## Features

- **38 tools** across 8 categories for comprehensive WordPress management
- **Application Passwords** authentication (secure, no plugins required)
- **Divi-compatible** — reads/writes Divi shortcode content via standard REST API
- **Rate limiting** with configurable token bucket
- **Health checks** for connection diagnostics

## Quick Start

### 1. Generate an Application Password

In your WordPress admin panel:
1. Go to **Users → Profile**
2. Scroll to **Application Passwords**
3. Enter a name (e.g., "Claude MCP") and click **Add New Application Password**
4. Copy the generated password (spaces are part of the password)

> Application Passwords require HTTPS on your site.

### 2. Register with Claude Code

```bash
claude mcp add wordpress -e WP_SITE_URL=https://your-site.com -e WP_USERNAME=admin -e WP_APPLICATION_PASSWORD="xxxx xxxx xxxx xxxx xxxx" -- node /path/to/wordpress-mcp/build/index.js
```

### 3. Build from Source

```bash
git clone https://github.com/gdamalis/wordpress-mcp.git
cd wordpress-mcp
npm install
npm run build
```

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `WP_SITE_URL` | Yes | — | WordPress site URL (must use HTTPS) |
| `WP_USERNAME` | Yes | — | WordPress username |
| `WP_APPLICATION_PASSWORD` | Yes | — | Application Password (include spaces) |
| `WP_RATE_LIMIT` | No | `30` | Max requests per rate window |
| `WP_RATE_WINDOW` | No | `10000` | Rate window in milliseconds |
| `WP_TIMEOUT` | No | `30000` | Request timeout in milliseconds |

## Tools Reference

### Content Management (10 tools)

| Tool | Description |
|---|---|
| `list_posts` | List posts with filters (status, category, tag, author, search, date range) |
| `get_post` | Get a single post by ID with full raw content |
| `create_post` | Create a new post (supports HTML and Divi shortcodes) |
| `update_post` | Update post fields |
| `delete_post` | Trash or permanently delete a post |
| `list_pages` | List pages with filters |
| `get_page` | Get a single page by ID with full raw content |
| `create_page` | Create a new page |
| `update_page` | Update page fields |
| `search_content` | Search across all content types |

### Media Management (4 tools)

| Tool | Description |
|---|---|
| `list_media` | List media library items |
| `get_media` | Get media item with all size URLs |
| `upload_media` | Upload from URL or base64 data |
| `update_media` | Update alt text, caption, description |

### Taxonomy Management (5 tools)

| Tool | Description |
|---|---|
| `list_categories` | List categories |
| `create_category` | Create a category |
| `list_tags` | List tags |
| `create_tag` | Create a tag |
| `manage_post_terms` | Set categories/tags on a post |

### Comment Moderation (4 tools)

| Tool | Description |
|---|---|
| `list_comments` | List comments with status filters |
| `get_comment` | Get comment details |
| `moderate_comment` | Change comment status (approve/hold/spam/trash) |
| `reply_to_comment` | Reply as the authenticated user |

### User Management (3 tools)

| Tool | Description |
|---|---|
| `list_users` | List users with role filters |
| `get_user` | Get user profile |
| `get_current_user` | Get the authenticated user's profile |

### Plugin & Theme Management (5 tools)

| Tool | Description |
|---|---|
| `list_plugins` | List installed plugins with status |
| `toggle_plugin` | Activate or deactivate a plugin |
| `list_themes` | List installed themes |
| `get_active_theme` | Get active theme details |
| `switch_theme` | Activate a different theme |

### Site Settings (4 tools)

| Tool | Description |
|---|---|
| `get_site_info` | Get site name, URL, WP version, namespaces |
| `get_settings` | Get site settings (title, tagline, timezone, etc.) |
| `update_settings` | Update site settings |
| `get_post_types` | List registered post types (discover Divi layouts) |

### Navigation Menus (3 tools)

| Tool | Description |
|---|---|
| `list_menus` | List navigation menus |
| `get_menu` | Get menu details |
| `update_menu` | Update menu name, description, locations |

### Health (2 tools)

| Tool | Description |
|---|---|
| `get_health` | Quick connection and auth check |
| `get_health_detailed` | Comprehensive check of all API endpoints |

## Divi Theme Support

This MCP works with Divi-powered sites through the standard WordPress REST API:

- **Reading Divi pages**: `get_post` and `get_page` return raw content with `context=edit`, exposing Divi shortcode structures like `[et_pb_section][et_pb_row]...`
- **Creating Divi pages**: Use `create_page` with Divi shortcodes in the `content` field
- **Updating Divi pages**: Modify shortcode content via `update_page`
- **Discovering Divi layouts**: Use `get_post_types` to find Divi's `et_pb_layout` custom post type (Divi Library items)

## Security

- HTTPS is enforced (Application Passwords are Base64-encoded and require transport encryption)
- Credentials are loaded from environment variables only, never stored on disk
- **Minimum role required**: Editor for content operations, Administrator for plugin/theme management
- Media uploads accept URLs and base64 only — no local filesystem access

## WordPress Role Requirements

| Tools | Minimum Role |
|---|---|
| Content, Media, Taxonomy, Comments | Editor |
| Users (read-only) | Author |
| Plugins, Themes, Settings | Administrator |

## License

MIT