# 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
```mermaid
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
```mermaid
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
```mermaid
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](https://github.com/Automattic/wp-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:
```bash
# 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](ARCHITECTURE.md)** - Technical details about the semantic operation engine
- **[Customization Guide](CUSTOMIZATION.md)** - Create custom personalities and tool mappings
- **[Page Creation Examples](docs/page-examples.md)** - Complete guide to creating and managing pages
- **[WordPress MCP Analysis](wordpress-mcp-analysis-report.md)** - Why we built this differently
- **[Test Documentation](tests/README.md)** - 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
```bash
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:
```bash
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/`:
```bash
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`
```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:
```bash
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`:
```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:
```json
{
"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:
```bash
npx wordpress-author-mcp --personality=editor
```
## Customization
See [CUSTOMIZATION.md](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
```bash
# Run in development mode with auto-reload
npm run dev
```
## License
MIT
