WordPress Author MCP Server

A personality-based Model Context Protocol (MCP) server for WordPress that provides role-appropriate tools for content management. This server enables AI assistants like Claude to create, edit, and manage WordPress content through natural language interactions.

Purpose & Features

• 🎭 Personality-Based Tool Mapping: Three modes (Contributor/Author/Administrator) with role-appropriate tools
• 🔧 Semantic Operations: High-level WordPress actions without API complexity
• 📁 Document Session Workflow: Abstracted temp file editing with opaque handles (no filesystem exposure)
• 🔄 Transparent Format Conversion: AI edits clean Markdown → WordPress receives formatted HTML
• ✏️ Flexible Line-Based Editing: Precise line operations + contextual search/replace
• 🛡️ WordPress-Native Permissions: Let WordPress handle all permission enforcement
• 📝 Content Management: Create drafts, publish posts/pages, schedule content, manage media
• ⚡ Map-Based Architecture: JSON configuration for tool assignments, no hardcoded roles

Semantic Architecture

This MCP server is not just an API wrapper. It provides intelligent semantic operations that map human workflows to WordPress actions, with sophisticated state management and format conversion.

Document Session State Flow

flowchart TB
    WP[WordPress HTML Post]:::wordpress
    PFE[pull-for-editing]:::operation
    H2M[HTML→Markdown Conversion]:::converter
    DS[Document Session<br/>Handle: abc123]:::session
    LES[Local Edit State<br/>• Clean Markdown<br/>• Line Numbers<br/>• No HTML Entities]:::state
    
    EDL[edit-document-line]:::edit
    IAL[insert-at-line]:::edit
    SR[search-replace]:::edit
    
    MLS[Modified Local State<br/>Multiple Edits Applied]:::state
    STW[sync-to-wordpress]:::operation
    M2H[Markdown→HTML Conversion]:::converter
    WPU[WordPress Update<br/>Single API Call]:::wordpress
    
    WP -->|1| PFE
    PFE --> H2M
    H2M --> DS
    DS --> LES
    LES --> EDL
    LES --> IAL
    LES --> SR
    EDL --> MLS
    IAL --> MLS
    SR --> MLS
    MLS -->|2| STW
    STW --> M2H
    M2H --> WPU
    
    classDef wordpress fill:#1e40af,stroke:#3730a3,color:#ffffff
    classDef operation fill:#059669,stroke:#047857,color:#ffffff
    classDef converter fill:#7c3aed,stroke:#6d28d9,color:#ffffff
    classDef session fill:#ea580c,stroke:#dc2626,color:#ffffff
    classDef state fill:#0891b2,stroke:#0e7490,color:#ffffff
    classDef edit fill:#64748b,stroke:#475569,color:#ffffff

Semantic Operation Mapping

flowchart LR
    subgraph "Human Intent"
        H1[I want to write about MCP servers]:::human
        H2[Fix that typo in my article]:::human
        H3[What do people think of my post?]:::human
    end
    
    subgraph "AI Intent"
        AI1[Create article]:::intent
        AI2[Edit my post]:::intent
        AI3[Review feedback]:::intent
    end
    
    subgraph "Semantic Operations"
        SO1[draft-article]:::semantic
        SO2[pull-for-editing<br/>+ edit-document<br/>+ sync-to-wordpress]:::semantic
        SO3[view-editorial-feedback]:::semantic
    end
    
    subgraph "WordPress API"
        API1[POST /wp/v2/posts<br/>+ Category lookups<br/>+ Tag creation<br/>+ Status setting]:::api
        API2[GET /wp/v2/posts/:id<br/>+ GET categories<br/>+ GET tags<br/>+ PUT /wp/v2/posts/:id]:::api
        API3[GET /wp/v2/comments<br/>+ Filter by post_author<br/>+ Parse editorial notes]:::api
    end
    
    H1 --> AI1
    H2 --> AI2
    H3 --> AI3
    
    AI1 --> SO1
    AI2 --> SO2
    AI3 --> SO3
    
    SO1 --> API1
    SO2 --> API2
    SO3 --> API3
    
    classDef human fill:#ec4899,stroke:#db2777,color:#ffffff
    classDef intent fill:#10b981,stroke:#059669,color:#ffffff
    classDef semantic fill:#f59e0b,stroke:#d97706,color:#000000
    classDef api fill:#6366f1,stroke:#4f46e5,color:#ffffff

Key Architectural Components

1. Document Session Manager

   • Maintains editing sessions with opaque handles
   • No filesystem paths exposed to AI
   • Automatic cleanup on sync

2. Format Conversion Layer

   • Turndown: HTML → Markdown (with fallbacks)
   • Marked: Markdown → HTML (with fallbacks)
   • Handles WordPress HTML entities transparently

3. Semantic Operation Engine

   • Maps high-level intents to WordPress workflows
   • Batches related API calls
   • Provides transaction-like operations

4. Line-Based Edit System

   • Precise line number operations
   • Context-aware search within line ranges
   • Avoids brittle string matching

Permission Flow

flowchart TD
    subgraph "MCP Configuration"
        P1[Contributor Personality]:::personality
        P2[Author Personality]:::personality
        P3[Admin Personality]:::personality
    end
    
    subgraph "Available Tools"
        T1[Limited Tools<br/>draft, edit, submit]:::tools
        T2[Extended Tools<br/>+ publish, media]:::tools
        T3[All Tools<br/>+ bulk ops, categories]:::tools
    end
    
    subgraph "WordPress User"
        U1[Contributor Account]:::user
        U2[Author Account]:::user
        U3[Admin Account]:::user
    end
    
    subgraph "Actual Capabilities"
        C1[Can only draft]:::capability
        C2[Can publish own]:::capability
        C3[Full control]:::capability
    end
    
    P1 --> T1
    P2 --> T2
    P3 --> T3
    
    T1 --> |Filtered by| U1
    T1 --> |Filtered by| U2
    T1 --> |Filtered by| U3
    
    T2 --> |Filtered by| U1
    T2 --> |Filtered by| U2
    T2 --> |Filtered by| U3
    
    T3 --> |Filtered by| U1
    T3 --> |Filtered by| U2
    T3 --> |Filtered by| U3
    
    U1 --> C1
    U2 --> C2
    U3 --> C3
    
    WP[WordPress Always Has<br/>Final Authority]:::wordpress
    C1 --> WP
    C2 --> WP
    C3 --> WP
    
    classDef personality fill:#8b5cf6,stroke:#7c3aed,color:#ffffff
    classDef tools fill:#0ea5e9,stroke:#0284c7,color:#ffffff
    classDef user fill:#f97316,stroke:#ea580c,color:#ffffff
    classDef capability fill:#22c55e,stroke:#16a34a,color:#000000
    classDef wordpress fill:#dc2626,stroke:#b91c1c,color:#ffffff

Prerequisites

Before using this MCP server, you need:

1. WordPress Application Password

   • Go to your WordPress admin: Users > Your Profile > Application Passwords
   • Create a new application password
   • Save this password - you'll need it for setup

2. WordPress Feature API Plugin

   • Install the WordPress Feature API plugin
   • Activate the plugin in your WordPress admin
   • This enables semantic operations beyond basic REST API

3. Appropriate WordPress User Permissions

   • The MCP server respects your WordPress user's actual permissions
   • Contributor personality + Admin account = Admin capabilities
   • Administrator personality + Contributor account = Contributor capabilities only
   • WordPress always has final authority on permissions

Quick Start

Once prerequisites are met:

# Clone and install
git clone https://github.com/aaronsb/wordpress-mcp
cd wordpress-mcp
npm install

# Run interactive setup
npm run setup

The setup wizard will:

1. Ask for your WordPress site URL and credentials
2. Help you choose a default personality (Contributor/Author/Administrator)
3. Create your .env configuration file
4. Generate ready-to-paste configurations for Claude Desktop and Claude Code

Important: The personality you choose determines which tools are available, but your actual WordPress user permissions always take precedence.

Documentation

• Architecture Overview - Technical details about the semantic operation engine
• Customization Guide - Create custom personalities and tool mappings
• Page Creation Examples - Complete guide to creating and managing pages
• WordPress MCP Analysis - Why we built this differently
• Test Documentation - Running and understanding the test suite

How It Works

1. Features are defined as standalone modules in src/features/
2. Personalities map to specific sets of features in config/personalities.json
3. At launch, specify a personality to expose only its mapped tools
4. WordPress handles all actual permission enforcement

Installation

git clone https://github.com/aaronsb/wordpress-mcp
cd wordpress-mcp
npm install

Configuration

1. WordPress Setup

The server looks for credentials in this order:

1. Environment variables (WORDPRESS_URL, WORDPRESS_USERNAME, WORDPRESS_APP_PASSWORD)
2. .env file in ~/.wordpress-mcp/ (recommended for global use)
3. .env file in the server directory (for development)

Option A: Use the Setup Wizard (Recommended)

Run the interactive setup:

npm run setup

This will:

• Ask where to save your credentials (global or local)
• Collect your WordPress site details
• Create the .env file automatically
• Show you ready-to-paste configurations

Option B: Manual Setup

Create a .env file in ~/.wordpress-mcp/:

mkdir -p ~/.wordpress-mcp
cat > ~/.wordpress-mcp/.env << EOF
WORDPRESS_URL=https://your-site.com
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=your-app-password
EOF

Note: Use Application Passwords for better security. Generate one at: Users > Your Profile > Application Passwords in your WordPress admin.

2. Claude Desktop Setup

First, ensure your credentials are configured (run npm run setup if needed).

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "wordpress-author": {
      "command": "node",
      "args": [
        "/path/to/wordpress-mcp/src/server.js",
        "--personality=author"
      ]
    }
  }
}

The server will read credentials from its .env file.

3. Claude Code Setup

Option A: Using the CLI (Recommended)

First, ensure your .env file is configured (run npm run setup if needed).

Then, in your project directory, run:

claude mcp add wordpress-author \
  node /path/to/wordpress-mcp/src/server.js -- \
  --personality=author

The server will read credentials from the .env file in the wordpress-mcp directory.

Option B: Manual Configuration

Alternatively, add to your project's .claude/settings.json:

{
  "mcpServers": {
    "wordpress-author": {
      "command": "node",
      "args": [
        "/path/to/wordpress-mcp/src/server.js",
        "--personality=author"
      ]
    }
  }
}

Note: The server reads credentials from its .env file, not from the Claude configuration.

Note: Adjust the personality parameter (--personality=) to one of:

• contributor - Limited tools for content creation
• author - Full authoring capabilities (recommended)
• administrator - Complete site management

Usage

Once configured, the WordPress tools will be available in Claude. You can:

• Create and edit draft posts and pages
• Publish articles and pages with scheduling options
• Create hierarchical page structures with parent-child relationships
• Search posts using natural language
• Pull posts/pages for editing with document sessions
• Edit content using line-based operations
• Sync changes back in single API call
• Manage media files
• Perform bulk operations (admin only)

Content Discovery & Editing Workflows

Semantic Search Examples:

• "Find my article about potatoes published yesterday"
• "Search for drafts mentioning MCP servers"
• "Show me posts about AI that need editing"
• "Find published articles with comments to review"

Natural Language Workflows:

• "Find my article about potatoes and update the cooking section" → AI uses find-posts → suggests pull-for-editing → guides you through edits
• "Review feedback on my WordPress tutorial" → AI searches published posts → uses view-editorial-feedback
• "Edit my latest draft about semantic APIs" → AI finds recent drafts → pulls for editing → helps with changes

Page-Specific Workflows:

• "Create an About Us page" → AI uses draft-page or create-page with clear semantic context
• "Make a Services page under the main Services section" → AI creates hierarchical page with parent relationship
• "Edit the Contact page to add new office hours" → AI uses pull-for-editing with type: "page"

Direct ID-Based Operations (when you know the ID):

• "Pull post 42 for editing"
• "Pull page 15 for editing"
• "Publish draft with ID 30"
• "Schedule post 55 for next Monday at 9 AM"

Intelligent Search with Intent

The find-posts operation understands what you want to do:

Intent-based filtering:

• intent: "edit" → Prioritizes drafts you can modify
• intent: "review" → Shows pending posts awaiting approval
• intent: "publish" → Finds drafts ready to go live
• intent: "comment" → Shows published posts with feedback

Workflow guidance: Each search result includes:

• Suggested next actions based on post status
• Clear instructions for the next step
• Role-appropriate tool recommendations

Example:

"Find posts about baking I can edit"
→ Returns drafts with suggested actions: ["pull-for-editing", "submit-for-review"]
→ Guidance: "📝 Use 'pull-for-editing' with a post ID to start editing..."

Document Editing Features

🔄 Transparent Format Conversion:

• WordPress HTML → Clean Markdown for AI editing
• AI edits in Markdown → WordPress receives formatted HTML
• Preserves bold, italic, headers, lists, and more
• No HTML entities or encoding issues

✏️ Flexible Editing Tools:

• read-document - View content with line numbers
• edit-document-line - Replace specific lines by number
• insert-at-line - Insert content at precise positions
• replace-lines - Replace multi-line blocks
• search-replace - Context-aware search with line proximity
• edit-document - Traditional string replacement (fallback)

Example Document Session Workflow

1. Pull for editing: pull-for-editing postId=42
   → Returns documentHandle="wp-session-abc123" (no filesystem paths!)

2. Read and edit using various methods:
   → read-document documentHandle="wp-session-abc123"
   → edit-document-line lineNumber=5 newLine="Better content"
   → insert-at-line lineNumber=10 content="New paragraph"
   → search-replace searchTerm="old" replacement="new" nearLine=15

3. Sync back:
   → sync-to-wordpress documentHandle="wp-session-abc123"
   → Single WordPress update with all formatting preserved

Key Benefits:

• AI never sees filesystem paths (security + abstraction)
• Edit in clean Markdown without HTML encoding issues
• WordPress receives properly formatted HTML automatically
• Line-based editing avoids string matching failures
• One pull → multiple edits → one push (API efficiency)

Personality Mappings

The tool mappings are defined in config/personalities.json:

Contributor

Content Creation:

• draft-article - Create draft posts
• draft-page - Create draft pages for static content
• edit-draft - Edit existing drafts
• submit-for-review - Submit drafts for editorial review
• view-editorial-feedback - See editor comments

Document Session Workflow:

• pull-for-editing - Fetch posts/pages into editing sessions
• read-document - Read documents with line numbers
• edit-document-line - Replace specific lines by number
• insert-at-line - Insert content at line positions
• replace-lines - Replace line ranges
• search-replace - Context-aware search and replace
• edit-document - String replacement (fallback)
• sync-to-wordpress - Push all changes back
• list-editing-sessions - View active sessions
• close-editing-session - Manual session cleanup

Author

• All contributor tools, plus:

Publishing:

• create-article - Create and publish posts immediately
• create-page - Create and publish pages with hierarchy
• publish-workflow - Publish or schedule posts
• manage-media - Upload and manage media files

Content Management:

• trash-own-content - Move your own posts or pages to trash

Administrator

• All author tools, plus:

Site Management:

• bulk-content-operations - Bulk actions on posts/pages (trash, restore, delete, change status)
• manage-all-content - View and manage all posts
• review-content - Review pending posts and comments
• moderate-comments - Approve, reject, or manage comments
• manage-categories - Create, update, and organize categories

Editor

• All author tools, plus:

Editorial Management:

• bulk-content-operations - Bulk actions on posts/pages (trash, restore, delete, change status)
• review-content - Review pending posts and comments
• moderate-comments - Approve, reject, or manage comments
• manage-categories - Create, update, and organize categories

Adding Custom Personalities

Edit config/personalities.json to create custom role mappings:

{
  "custom-editor": {
    "name": "Custom Editor",
    "description": "Custom editorial team member",
    "features": ["manage-all-content", "edit-draft", "publish-workflow", "bulk-content-operations"],
    "context": {
      "can_publish": true,
      "can_edit_others": true
    }
  }
}

Then launch with:

npx wordpress-author-mcp --personality=editor

Customization

See CUSTOMIZATION.md for detailed instructions on:

• Creating custom personalities
• Adding new features
• Configuring role-based tool mappings
• Real-world examples (Editor, Reviewer, Social Media Manager)

Architecture Benefits

1. No hardcoded roles - All personality logic lives in configuration
2. Easy customization - Modify JSON to change tool availability
3. WordPress authority - The API enforces actual permissions
4. Clean separation - Features don't know about personalities
5. Extensible - Add features and map them without touching core code

WordPress Permission Handling

The MCP server presents tools based on personality, but WordPress always has final authority:

• If a contributor tries to publish (via API manipulation), WordPress returns 403
• If an author tries to edit others' posts, WordPress denies it
• The MCP server gracefully handles these errors with helpful messages

Development

# Run in development mode with auto-reload
npm run dev

License

MIT