# WordPress MCP Python

A lightweight **standalone Python MCP server** that connects to WordPress via REST API.

## Features

- Standalone Python package - Runs independently, no WordPress plugin needed
- Easy setup with `pip install`
- Full WordPress REST API support: Posts, Pages, Categories, Tags, Users, Media, Settings
- WooCommerce support: Products, Orders (optional)
- MCP SDK integration for Claude Desktop
- Async/await for better performance

## Requirements

- Python 3.8+
- WordPress site with REST API enabled
- Application Password or JWT token

## Installation

### From PyPI (recommended)

```bash
pip install wordpress-mcp
```

### From source

```bash
git clone https://github.com/tannht/wordpress-mcp-python.git
cd wordpress-mcp-python
pip install -e .
```

## Configuration

### 1. Get WordPress Application Password

1. Go to WordPress Admin → Users → Profile
2. Scroll down to **Application Passwords**
3. Create a new one (name it "MCP")
4. Copy the generated password

Format: `abcd-efgh-ijkl-mnop` (4 groups of 4 chars)

### 2. Set Environment Variables

```bash
export WP_URL="https://yoursite.com"
export WP_USERNAME="your_username"
export WP_PASSWORD="your_application_password"
```

Or use JWT token:

```bash
export WP_URL="https://yoursite.com"
export WP_JWT_TOKEN="your_jwt_token"
```

## Usage

### As a Library

```python
import asyncio
from wordpress_mcp import WordPressClient

async def main():
    client = WordPressClient(
        base_url="https://yoursite.com",
        username="your_username",
        password="your_app_password"
    )

    # Create a post
    post = await client.create_post(
        title="Hello from Python!",
        content="This post was created via Python MCP.",
        status="draft"
    )
    print(f"Created post: {post['id']}")

asyncio.run(main())
```

### As MCP Server (for Claude Desktop)

```bash
# Run the MCP server
python -m wordpress_mcp
```

### Claude Desktop Integration

Add to your Claude Desktop config:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "wordpress": {
      "command": "python",
      "args": ["-m", "wordpress_mcp"],
      "env": {
        "WP_URL": "https://yoursite.com",
        "WP_USERNAME": "your_username",
        "WP_PASSWORD": "your_application_password"
      }
    }
  }
}
```

### Docker

Build and run the MCP server using Docker:

```bash
# Build and start the server
docker compose up -d --build

# View logs
docker compose logs -f

# Stop the server
docker compose down
```

The server runs on stdio transport and connects to WordPress via REST API.

**Environment Variables**

Create a `.env` file in the project root:

```bash
WP_URL=https://yoursite.com
WP_USERNAME=your_username
WP_PASSWORD=your_application_password
# Or use JWT token
# WP_JWT_TOKEN=your_jwt_token
```

### Claude Code Integration

Add the WordPress MCP server to Claude Code:

```bash
claude mcp add --transport stdio wordpress \
  --env WP_URL=https://yoursite.com \
  --env WP_USERNAME=your_username \
  --env WP_PASSWORD=your_application_password \
  -- wordpress-mcp
```

Verify connection:
```bash
claude mcp list
```

## MCP Tools Available

### Posts
- `wp_posts_search` - Search posts with pagination
- `wp_get_post` - Get post by ID
- `wp_add_post` - Create new post
- `wp_update_post` - Update post
- `wp_delete_post` - Delete post

### Pages
- `wp_pages_search` - Search pages
- `wp_get_page` - Get page by ID
- `wp_add_page` - Create new page

### Categories
- `wp_list_categories` - List all categories
- `wp_add_category` - Add new category

### Tags
- `wp_list_tags` - List all tags
- `wp_add_tag` - Add new tag

### Users
- `wp_users_search` - Search users
- `wp_get_user` - Get user by ID

### Media
- `wp_media_search` - Search media items

### Settings
- `wp_get_site_info` - Get site information
- `wp_get_settings` - Get site settings

### WooCommerce (optional)
- `wc_products_search` - Search products
- `wc_get_product` - Get product by ID
- `wc_add_product` - Create product
- `wc_orders_search` - Search orders
- `wc_get_order` - Get order by ID

## Development

### Setup Development Environment

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=wordpress_mcp

# Format code
black src/ tests/

# Lint
ruff check src/ tests/
```

### Project Structure

```
wordpress-mcp-python/
├── pyproject.toml         # Project metadata, dependencies
├── README.md
├── .gitignore
├── src/
│   └── wordpress_mcp/
│       ├── __init__.py    # Package init, entry point
│       ├── client.py      # WordPress REST API client
│       └── server.py      # MCP server implementation
├── tests/
│   ├── __init__.py
│   ├── conftest.py        # Pytest fixtures
│   └── test_client.py     # Client tests
└── scripts/
    └── test_connection.py # Connection test script
```

## Troubleshooting

### Connection refused
- Make sure WordPress REST API is enabled
- Check your site URL is correct (include https://)

### Authentication failed
- Verify Application Password is correct
- Ensure username has proper permissions

### Import errors
- Check Python version (3.8+ required)
- Install with `pip install -e .` for development

## Comparison: Python vs PHP

| Feature | Python MCP | PHP Plugin |
|---------|-----------|-----------|
| Installation | pip install | Upload plugin |
| Size | ~50KB | ~160KB |
| Dependencies | mcp, httpx, pyjwt | firebase/php-jwt |
| Location | Runs anywhere | Must be in WordPress |
| Update | git pull | Plugin update |

## License

MIT

## Credits

Based on WordPress MCP by Automattic.