WordPress Author MCP Server

A personality-based MCP server for WordPress, providing role-appropriate tools for content management.

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.

- 🎭 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

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

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

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

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

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

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

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

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

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

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

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

- 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
- Featuresare defined as standalone modules insrc/features/
- Personalitiesmap to specific sets of features inconfig/personalities.json
- At launch, specify a personality to expose only its mapped tools
- WordPresshandles all actual permission enforcement

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

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

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

The server will read credentials from its.envfile.

First, ensure your.envfile is configured (runnpm run setupif needed).

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

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

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.envfile, 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

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

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

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

- "Create an About Us page" → AI usesdraft-pageorcreate-pagewith 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 usespull-for-editingwithtype: "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"

Thefind-postsoperation understands what you want to do:

- 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

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

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

- 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)

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

- 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)

The tool mappings are defined inconfig/personalities.json:

- 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

- 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

- 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

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

- 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

- 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

Editconfig/personalities.jsonto 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 } } }

npx wordpress-author-mcp --personality=editor

SeeCUSTOMIZATION.mdfor detailed instructions on:

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

An MCP server for WordPress plugin audits