WordPress MCP Site Management

Manage WordPress sites through a single Python MCP proxy server (wordpress in ~/.claude.json). All tools require a site parameter identifying the target site. Sites are configured in sites.json.

Setup

This skill requires the WordPress MCP server. If the wordpress MCP tools are not yet available, set up the full project from https://github.com/5unnykum4r/wordpress-mcp:

1. Clone the repo and install the PHP adapter on your WordPress site (wordpress/ directory)
2. Create a WordPress Application Password and add your site to sites.json
3. Add the MCP server to ~/.claude.json:

{
  "mcpServers": {
    "wordpress": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "--with", "httpx", "python", "/path/to/wordpress-mcp/server.py"]
    }
  }
}

See SETUP.md in the repo for the full step-by-step guide.

How It Works

A Python FastMCP server proxies tool calls to any WordPress site:

1. Every tool takes site as the first parameter (e.g. site="myblog")
2. The proxy looks up credentials in sites.json
3. Sends JSON-RPC requests to the WordPress MCP adapter endpoint
4. Authentication uses WordPress Application Passwords via HTTP Basic Auth

Use list_sites to see all configured sites.

Available Tools

See references/posts.md, references/categories-tags.md, references/media.md, references/comments.md, references/redirections.md, references/admin.md, and references/tablepress.md for full parameter details.

Quick Reference

All tools require site as the first parameter.

Rank Math SEO

Posts and categories support a rank_math object on create/update.

Post fields:

title, description, focus_keyword, canonical_url, robots[],
primary_category, pillar_content, breadcrumb_title, schema_type,
og_title, og_description, og_image, twitter_title, twitter_description

Category fields:

title, description, focus_keyword, canonical_url, robots[],
breadcrumb_title, og_title, og_description, og_image,
twitter_title, twitter_description

read_post and list_categories return all Rank Math fields.

Gutenberg Blocks

Post content is stored as Gutenberg block markup. read_post returns the raw block HTML including <!-- wp:block-name --> delimiters. create_post and update_post accept full block markup in the content field — block comments are preserved as-is.

Use list_block_types to discover all registered blocks (core + custom). Pass custom_only=True to see only theme/plugin blocks, or namespace="your-theme" to filter by namespace. Each block entry includes its attribute schema so you can construct valid block markup.

Block markup format:

<!-- wp:namespace/block-name {"attribute":"value"} -->
<div class="wp-block-namespace-block-name">Inner HTML</div>
<!-- /wp:namespace/block-name -->

When updating an existing post's content, always read_post first to get the full block markup, modify the specific blocks, then pass the entire content back.

Common Workflows

Create an optimized post

1. upload_image(site="myblog", image_url="...") — upload featured image
2. create_post(site="myblog", title="...", content="...", categories=["Tech"], rank_math={...}) — create with SEO
3. read_post(site="myblog", post_id=123) — verify
4. update_post(site="myblog", post_id=123, status="publish") — publish

Bulk SEO audit

1. list_posts(site="myblog", number=50) — get all published posts
2. read_post(site="myblog", post_id=X) — check rank_math fields
3. update_post(site="myblog", post_id=X, rank_math={...}) — fix missing SEO

Manage redirects after slug change

1. read_post(site="myblog", post_id=123) — get current slug
2. update_post(site="myblog", post_id=123, slug="new-slug") — change slug
3. create_redirection(site="myblog", from_url="/old-slug", to="/new-slug", type=301) — redirect

Search and replace

1. search_replace(site="myblog", search="old text", replace="new text", dry_run=True) — preview
2. search_replace(site="myblog", search="old text", replace="new text", dry_run=False) — execute

Create a reusable synced pattern

1. create_pattern(site="myblog", title="CTA Banner", content="<!-- wp:group -->...") — returns ref block markup
2. Use the returned ref_block (e.g. <!-- wp:block {"ref":456} /-->) in any post content
3. Updating the pattern auto-updates every post that references it

Create a post with custom Gutenberg blocks

1. list_block_types(site="myblog", custom_only=True) — discover custom blocks and their attributes
2. Build block markup: <!-- wp:namespace/block-name {"attr":"value"} -->\n<div>...</div>\n<!-- /wp:namespace/block-name -->
3. create_post(site="myblog", title="...", content="...block markup...", rank_math={...}) — create post
4. read_post(site="myblog", post_id=123) — verify block content preserved

Edit blocks in an existing post

1. read_post(site="myblog", post_id=123) — get current block markup from content
2. Modify the specific <!-- wp:... --> blocks in the content string
3. update_post(site="myblog", post_id=123, content="...updated full content...") — save back

Create and embed a TablePress table

1. create_tablepress_table(site="myblog", name="Pricing", data=[["Plan","Price"],["Basic","$9"],["Pro","$29"]]) — returns id + shortcode
2. update_post(site="myblog", post_id=123, content="... [table id=5 /] ...") — embed in post
3. read_tablepress_table(site="myblog", table_id="5") — verify

Managing Sites

Sites are configured in sites.json:

{
  "myblog": {
    "url": "https://example.com/wp-json/mcp/mcp-adapter-default-server",
    "username": "AdminUsername",
    "password": "xxxx xxxx xxxx xxxx xxxx xxxx"
  }
}

To add a new site: install the MCP adapter on the WordPress server (see SETUP.md), create an Application Password, and add an entry to sites.json. No restart needed.

Site-Specific Extensions

For sites with custom workflows (e.g. ACF custom fields, specific content templates, SEO recovery plans), create additional skill files alongside this one and reference them from your project's CLAUDE.md or .claude/skills/ directory.

Example structure:

~/.claude/skills/
├── wordpress-mcp/         ← This skill (generic WordPress tools)
│   ├── SKILL.md
│   └── references/
└── my-site-workflow/      ← Your custom skill (site-specific context)
    └── SKILL.md