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)

pip install wordpress-mcp

From source

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

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

Or use JWT token:

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

Usage

As a Library

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)

# 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

{
  "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:

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

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:

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:

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

# 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.