WordPress Ultimate MCP Server

The most comprehensive WordPress Model Context Protocol (MCP) server for AI assistants. Edit any WordPress page builder with precision and control.

Supported Page Builders

Tier 1: Full Support (Read, Write, Create, Delete)

• ✅ Gutenberg - WordPress Core Block Editor
• ✅ Elementor - Most popular visual page builder
• ✅ Divi Builder - Elegant Themes page builder
• ✅ Beaver Builder - Professional page builder
• ✅ WPBakery - Visual Composer
• ✅ Oxygen Builder - Advanced site builder
• ✅ Bricks Builder - Modern visual site builder

Tier 2: Read & Analysis Support

• ✅ Breakdance - Element Studio
• ✅ Brizy - Cloud-based builder
• ✅ Thrive Architect - Conversion-focused builder
• ✅ SiteOrigin - Page Builder by SiteOrigin
• ✅ Kadence Blocks - Gutenberg-based
• ✅ Spectra - Ultimate Addons for Gutenberg
• ✅ GenerateBlocks - Lightweight Gutenberg blocks
• ✅ Themify Builder - Drag & drop builder
• ✅ Zion Builder - Frontend page builder

Features

Universal Capabilities

• 🔍 Auto-Detection: Automatically detects which page builder(s) a post uses
• 📊 Structure Analysis: Get detailed statistics about page structure
• 📝 Text Extraction: Extract all text content regardless of builder
• 🔄 Unified Format: Convert between different builder formats
• 🔐 Multiple Connections: Supports both MySQL and REST API access

Per-Builder Capabilities

Gutenberg / Kadence / Spectra / GenerateBlocks

• Parse block structures with attributes
• Find blocks by type
• Update block attributes
• Add/remove blocks
• Nested block support
• Block validation

Elementor

• Parse sections, columns, and widgets
• Find elements by type or widget type
• Update widget settings
• Create new sections/columns/widgets
• Delete elements
• Clone elements
• Structure validation

Divi Builder

• Parse modules from shortcode or JSON
• Find modules by type
• Update module settings
• Create new sections/rows/columns/modules
• Shortcode generation
• JSON serialization

Beaver Builder

• Parse rows, columns, and modules
• Node-based editing
• Update module settings
• Add new modules
• Clone layouts
• PHP serialization support

WPBakery (Visual Composer)

• Parse shortcode structure
• Find elements by tag
• Update attributes
• Nested shortcode support

Oxygen Builder

• Parse JSON (4.0+) or shortcode (legacy)
• Find elements by name
• Update element options
• Support for both modern and legacy formats

Bricks Builder

• Parse serialized PHP data
• Element-based architecture
• Update settings
• Parent-child relationships
• Clone elements

Installation

cd mcp-servers/wordpress-ultimate
npm install
npm run build

Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Configure your WordPress connection (choose one or both):

Option A: Direct Database Access (Recommended)

WORDPRESS_DB_HOST=localhost
WORDPRESS_DB_PORT=3306
WORDPRESS_DB_USER=wordpress_user
WORDPRESS_DB_PASSWORD=your_password
WORDPRESS_DB_NAME=wordpress
WORDPRESS_TABLE_PREFIX=wp_

Option B: WordPress REST API

WORDPRESS_SITE_URL=https://your-site.com
WORDPRESS_USERNAME=admin
WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx

To create an Application Password:

1. Go to WordPress Admin → Users → Profile
2. Scroll to "Application Passwords"
3. Enter name: "MCP Server"
4. Click "Add New Application Password"
5. Copy the generated password

Usage with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "wordpress-ultimate": {
      "command": "node",
      "args": [
        "/path/to/brainstorm-app/mcp-servers/wordpress-ultimate/dist/index.js"
      ],
      "env": {
        "WORDPRESS_DB_HOST": "localhost",
        "WORDPRESS_DB_USER": "wordpress",
        "WORDPRESS_DB_PASSWORD": "password",
        "WORDPRESS_DB_NAME": "wordpress"
      }
    }
  }
}

Available Tools

Detection & Analysis

wordpress_detect_builder

Detect which page builder(s) are used by a post.

{
  post_id: number
}

Returns: Builder detection results with confidence levels and compatibility info.

get_page_structure

Get high-level overview of page structure including statistics.

{
  post_id: number
}

extract_all_text

Extract all text content from a post (works with any builder).

{
  post_id: number
}

WordPress Core

wordpress_get_post_content

Get complete post data with parsed builder content.

{
  post_id: number,
  parse_content?: boolean  // default: true
}

wordpress_update_post_content

Update post content and/or page builder data.

{
  post_id: number,
  content?: string,
  builder_data?: object,
  title?: string
}

wordpress_search_posts

Search for posts by criteria.

{
  post_type?: string,      // default: 'any'
  post_status?: string,    // default: 'any'
  search?: string,
  limit?: number,          // default: 10
  offset?: number          // default: 0
}

Gutenberg Tools

gutenberg_parse_blocks

Parse Gutenberg blocks from post content.

gutenberg_find_blocks

Find blocks of specific type.

{
  post_id: number,
  block_type: string  // e.g., 'core/paragraph'
}

gutenberg_update_blocks

Update all blocks in a post.

{
  post_id: number,
  blocks: Array<GutenbergBlock>
}

Elementor Tools

elementor_get_elements

Get complete Elementor page structure.

elementor_find_elements

Find elements by type.

{
  post_id: number,
  el_type?: 'section' | 'column' | 'widget',
  widget_type?: string  // e.g., 'heading', 'text-editor'
}

elementor_update_element

Update element settings.

{
  post_id: number,
  element_id: string,
  settings: object
}

elementor_add_element

Add new element to parent.

{
  post_id: number,
  parent_id: string,
  element_type: 'section' | 'column' | 'widget',
  widget_type?: string,
  settings?: object,
  position?: number
}

elementor_delete_element

Delete element and children.

{
  post_id: number,
  element_id: string
}

Divi Tools

divi_get_modules

Get all Divi modules from post.

divi_find_modules

Find modules by type.

{
  post_id: number,
  module_type: string  // e.g., 'et_pb_text'
}

divi_update_modules

Update Divi modules.

{
  post_id: number,
  modules: Array<DiviModule>
}

Beaver Builder Tools

beaver_builder_get_layout

Get complete layout structure.

beaver_builder_find_modules

Find modules by type.

{
  post_id: number,
  module_type?: string  // e.g., 'rich-text', 'photo'
}

beaver_builder_update_module

Update module settings.

{
  post_id: number,
  node_id: string,
  settings: object
}

beaver_builder_add_module

Add new module to column.

{
  post_id: number,
  parent_id: string,
  module_type: string,
  settings?: object
}

Architecture

Parser System

Each page builder has a dedicated parser that handles:

• Parsing from native format (JSON, serialized PHP, shortcodes, HTML comments)
• Serializing back to native format
• Converting to/from unified format for cross-builder compatibility
• Finding and updating elements
• Extracting text content
• Validating structure

Connection Layer

Dual connection support:

• MySQL Direct: Fastest, full access to all meta fields
• REST API: Remote access, standard WordPress authentication

Builder Detection

Intelligent multi-builder detection:

• Checks post_meta keys for builder-specific markers
• Analyzes post_content for builder signatures
• Returns confidence scores
• Detects multiple builders on same post
• Provides compatibility recommendations

Type Definitions

BuilderType

type BuilderType =
  | 'gutenberg'
  | 'elementor'
  | 'divi'
  | 'beaver-builder'
  | 'wpbakery'
  | 'oxygen'
  | 'bricks'
  | 'breakdance'
  | 'brizy'
  | 'thrive-architect'
  | 'siteorigin'
  | 'kadence'
  | 'spectra'
  | 'generateblocks'
  | 'themify'
  | 'zion'
  | 'unknown'

UnifiedElement

interface UnifiedElement {
  id: string
  type: string
  tag?: string
  settings: Record<string, any>
  content?: string
  children?: UnifiedElement[]
  builder: BuilderType
  rawData?: any
}

Examples

Example 1: Update Elementor Heading

// Find all heading widgets
const headings = await elementor_find_elements({
  post_id: 123,
  el_type: 'widget',
  widget_type: 'heading'
})

// Update the first heading
await elementor_update_element({
  post_id: 123,
  element_id: headings[0].id,
  settings: {
    title: 'New Heading Text',
    size: 'h1'
  }
})

Example 2: Add New Divi Section

// Get existing modules
const modules = await divi_get_modules({ post_id: 123 })

// Add new section with row and text
const newModules = [
  ...modules,
  {
    type: 'et_pb_section',
    attrs: { fullwidth: 'off' },
    children: [{
      type: 'et_pb_row',
      attrs: {},
      children: [{
        type: 'et_pb_column',
        attrs: { type: '4_4' },
        children: [{
          type: 'et_pb_text',
          attrs: {},
          content: '<p>New section content</p>'
        }]
      }]
    }]
  }
]

// Update post
await divi_update_modules({
  post_id: 123,
  modules: newModules
})

Example 3: Extract All Text from Any Page

// Works with any builder!
const result = await extract_all_text({ post_id: 123 })

console.log(result.builder)      // 'elementor'
console.log(result.text)         // 'All extracted text...'
console.log(result.word_count)   // 450

Example 4: Detect Builder Before Editing

// Always detect first to avoid errors
const detection = await wordpress_detect_builder({ post_id: 123 })

console.log(detection.primary_builder)  // 'beaver-builder'
console.log(detection.detections)       // Array of all detected builders
console.log(detection.compatibility)    // Warnings and recommendations

if (detection.compatibility.canEdit) {
  // Safe to proceed with edits
}

Development

Project Structure

src/
├── index.ts              # Main MCP server
├── detector.ts           # Builder detection logic
├── database/
│   └── connection.ts     # WordPress database/API layer
├── parsers/
│   ├── gutenberg.ts      # Gutenberg block parser
│   ├── elementor.ts      # Elementor parser
│   ├── divi.ts           # Divi Builder parser
│   ├── beaver-builder.ts # Beaver Builder parser
│   ├── wpbakery.ts       # WPBakery parser
│   ├── oxygen.ts         # Oxygen Builder parser
│   └── bricks.ts         # Bricks Builder parser
└── types/
    └── builders.ts       # Type definitions

Adding New Builder Support

1. Create parser in src/parsers/:

export class NewBuilderParser {
  parse(data: string): Element[] { }
  serialize(elements: Element[]): string { }
  toUnified(elements: Element[]): UnifiedElement[] { }
  fromUnified(elements: UnifiedElement[]): Element[] { }
}

2. Add detection in src/detector.ts:

private isNewBuilder(post: WordPressPost): boolean {
  return !!post.post_meta?.new_builder_meta_key
}

3. Add tools in src/index.ts
4. Update type definitions in src/types/builders.ts

Running Tests

npm test

Building

npm run build

Development Mode

npm run dev

Security Considerations

1. Database Access: Use read-only credentials when possible
2. Application Passwords: Create unique passwords per integration
3. Environment Variables: Never commit .env files
4. Input Validation: All inputs are validated before database queries
5. SQL Injection: Uses parameterized queries throughout
6. XSS Prevention: Content is properly escaped

Performance

• Direct Database: ~10-50ms per operation
• REST API: ~100-500ms per operation
• Caching: Connection pooling for database
• Batch Operations: Support for bulk updates
• Lazy Loading: Parsers loaded on-demand

Troubleshooting

"Could not detect page builder"

• Verify the post actually uses a page builder
• Check that builder plugin is active
• Ensure post_meta is accessible

"Invalid serialized data"

• Beaver Builder/Bricks: Check PHP serialization format
• May indicate corrupted post_meta

"REST API error: 401"

• Verify Application Password is correct
• Check username matches WordPress user
• Ensure REST API is not disabled

"MySQL connection failed"

• Verify database credentials
• Check firewall allows MySQL port
• Confirm database exists

Contributing

This is part of the Brainstorm AI platform. For issues or feature requests, please contact the development team.

License

MIT License - See LICENSE file for details

Credits

Built with:

• @modelcontextprotocol/sdk - MCP Server SDK
• mysql2 - MySQL client
• serialize-php - PHP serialization
• cheerio - HTML parsing

WordPress Ultimate MCP Server - The most comprehensive WordPress editing solution for AI assistants.