Elementor WordPress MCP Server v1.6.8

A powerful, modular Model Context Protocol (MCP) server for WordPress and Elementor. This server provides AI assistants with scalable capabilities—from basic content management to advanced page building—through an intelligent configuration system.

🆕 What's New in v1.6.8

• 📚 Documentation Update: Updated README to reflect all v1.6.7 improvements and fixes
• 🚨 Critical Tool Fixes: Resolved missing clear_elementor_cache tool implementation (Issues #14, #15)
• 📋 100% Structured Response Format: Complete elimination of legacy response formats across all 34+ tools
• 🔧 Enhanced Error Handling: All MCP errors now return structured JSON instead of plain text (Issue #16)
• 🎯 Complete Issue Resolution: Resolved 20 GitHub issues (#10-26) for production-grade reliability
• ✨ Zero Technical Debt: All legacy {content: [{type: 'text', text: '...'}]} formats eliminated
• 🚀 Production Ready: 120/120 tool validation with 100% success rate
• 🛡️ Enterprise-Grade Reliability: Comprehensive error management with actionable error codes
• 📊 Rich Metadata: Enhanced operation context and detailed success/error information
• ⚡ Performance Tools: Cache management now fully operational for optimization
• 🔐 SSL Certificate Support: Automatic SSL handling for local development sites (.local, .dev, .test, localhost)
• 📚 Complete Documentation: Enhanced setup guides, troubleshooting, and comprehensive changelog

✨ Key Features

• Modular Configuration: Scale from 20 to 34 tools based on your needs
• Complete Page Building: Create sections, containers, widgets, and complex layouts
• Performance Optimized: Incremental updates, chunked data, smart caching
• User-Centric Design: Essential → Standard → Advanced → Full progression
• True Elementor Integration: Direct manipulation of sections, columns, and widgets
• Universal Compatibility: Works with posts, pages, and custom post types
• Production Ready: Type-safe, thoroughly tested, comprehensive documentation

🎯 Quick Start

Choose your complexity level:

# Essential Mode (20 tools) - Perfect for beginners
ELEMENTOR_MINIMAL_MODE=true npx wp-elementor-mcp

# Standard Mode (32 tools) - Great for most users (default)
npx wp-elementor-mcp

# Advanced Mode (34 tools) - For power users  
ELEMENTOR_MCP_MODE=advanced npx wp-elementor-mcp

# Full Mode (34 tools) - Everything enabled (requires Elementor Pro)
ELEMENTOR_ENABLE_ALL=true npx wp-elementor-mcp

📊 Configuration Modes

Mode	Tools	Best For	Capabilities
Essential	20	Learning, basic tasks	WordPress CRUD + Basic Elementor
Standard	32	Most users	+ Page building & element management
Advanced	34	Power users	+ Performance tools & advanced operations
Full	34	Pro workflows	+ Templates, global settings, revisions*

*Pro features require Elementor Pro license

🛠️ Prerequisites

• Node.js 18+
• WordPress site with REST API enabled
• WordPress Application Password (not regular password)
• Elementor plugin (for page building features)
• Elementor Pro (optional, for template and global features)

📦 Installation

Option 1: NPX (Recommended)

npx wp-elementor-mcp

Option 2: Local Development

git clone https://github.com/Huetarded/wp-elementor-mcp.git
cd wp-elementor-mcp
npm install
npm run build

Option 3: Global Installation

npm install -g wp-elementor-mcp
wp-elementor-mcp

⚙️ WordPress Setup

1. Create Application Password

1. WordPress Admin → Users → Profile
2. Scroll to Application Passwords
3. Add name: "MCP Server"
4. Copy the generated password immediately!

2. User Permissions

Ensure your WordPress user can:

• Create/edit/delete posts and pages
• Upload media files
• Access Elementor data

🔌 MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "elementor-wordpress": {
      "command": "npx",
      "args": ["wp-elementor-mcp"],
      "env": {
        "ELEMENTOR_MCP_MODE": "standard",
        "WORDPRESS_BASE_URL": "https://yoursite.com",
        "WORDPRESS_USERNAME": "your-username",
        "WORDPRESS_APPLICATION_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Continue.dev

{
  "name": "elementor-wordpress",
  "command": "npx",
  "args": ["wp-elementor-mcp"],
  "env": {
    "ELEMENTOR_MCP_MODE": "advanced",
    "WORDPRESS_BASE_URL": "https://yoursite.com",
    "WORDPRESS_USERNAME": "your-username", 
    "WORDPRESS_APPLICATION_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
  }
}

Environment Variables

Mode Selection

# Primary mode setting
ELEMENTOR_MCP_MODE=essential    # 21 tools - Basic WordPress + Elementor
ELEMENTOR_MCP_MODE=standard     # 33 tools - + Page building (default)
ELEMENTOR_MCP_MODE=advanced     # 35 tools - + Performance tools
ELEMENTOR_MCP_MODE=full         # 35 tools - + Pro features (stubs)

# Quick mode shortcuts
ELEMENTOR_MINIMAL_MODE=true     # Same as essential mode
ELEMENTOR_ENABLE_ALL=true       # Same as full mode

WordPress Connection

WORDPRESS_BASE_URL=https://yoursite.com
WORDPRESS_USERNAME=your-username
WORDPRESS_APPLICATION_PASSWORD=xxxx xxxx xxxx xxxx

Individual Feature Toggles (optional)

ELEMENTOR_ENABLE_TEMPLATES=true
ELEMENTOR_ENABLE_PERFORMANCE=true

🎛️ Available Tools by Mode

Essential Mode (20 tools)

WordPress Operations:

• get_posts, get_post, create_post, update_post
• get_pages, create_page, update_page
• get_media, upload_media
• list_all_content - Content discovery with Elementor status

Basic Elementor:

• get_elementor_templates, get_elementor_data, update_elementor_data
• get_elementor_widget, update_elementor_widget, get_elementor_elements
• update_elementor_section, get_elementor_data_chunked
• backup_elementor_data, clear_elementor_cache

Standard Mode (+12 tools = 32 total)

Section & Container Creation:

• create_elementor_section - Create sections with columns
• create_elementor_container - Create Flexbox containers
• add_column_to_section - Add columns to sections
• duplicate_section - Clone sections with content

Widget Management:

• add_widget_to_section - Add widgets to containers
• insert_widget_at_position - Insert at specific positions
• clone_widget - Duplicate widgets
• move_widget - Move widgets between containers

Element Operations:

• delete_elementor_element - Remove elements safely
• reorder_elements - Change element order
• copy_element_settings - Copy settings between elements

Page Analysis:

• get_page_structure - Get simplified page overview

Advanced Mode (+2 tools)

Performance:

• clear_elementor_cache_by_page - Page-specific cache clearing

Advanced Operations:

• find_elements_by_type - Search elements by type

Full Mode (+0 new tools, enables Pro features)

Currently implemented as stubs - requires Elementor Pro integration

• Template management capabilities
• Global color and font settings
• Custom field integration
• Revision and history features

💡 Example Usage

Basic Content Management

Create a new WordPress page titled "About Us" with a professional layout

Elementor Page Building

Create a new section in page ID 123 with 3 columns, then add a heading widget to the first column with the text "Welcome to Our Site"

Advanced Layout Creation

Duplicate the hero section from page 45, then move the call-to-action button widget to the second column and change its text to "Get Started Today"

Performance-Optimized Updates

Update only the HTML widget with ID "abc123" in page 67 to show our latest promotion, without loading the entire page data

Element Discovery

Show me all the text and heading widgets on page 89 so I can update the content

📚 Documentation

User Guides

• TROUBLESHOOTING.md - Complete troubleshooting guide for common issues
• CREDENTIAL-TESTING.md - Step-by-step testing with WordPress credentials
• SSL-SUPPORT.md - SSL certificate setup for local development
• TESTING.md - Comprehensive testing guide and test suite documentation

Developer Resources

• CONTRIBUTING.md - How to contribute to the project
• CHANGELOG.md - Release history and version changes

Quick Reference

• Configuration: Environment variables and mode selection (see above)
• Troubleshooting: 404 errors, connection issues, SSL problems → TROUBLESHOOTING.md
• Testing: Validate your setup → CREDENTIAL-TESTING.md
• Development: Local setup and contribution → CONTRIBUTING.md

🚀 Development & Testing

NPM Scripts

npm run build                    # Build TypeScript
npm run start                    # Standard mode
npm run start:essential          # Essential mode  
npm run start:advanced           # Advanced mode
npm run start:full              # Full mode
npm run test:config             # Test configuration system

Comprehensive Testing Suite

Quick Server Test:

npm test                         # Basic connectivity test

Schema & Structure Validation (No WordPress required):

npm run test:validate           # Validate all tool schemas

• ✅ 100% validation rate achieved
• Tests all 120 tools across 4 modes
• Validates naming conventions and descriptions
• Checks input schema integrity

Full Functionality Test (WordPress credentials required):

npm run test:comprehensive      # Test actual functionality

• ✅ 100% Success Rate: All 124 tools pass validation tests
• Tests tool execution and response handling
• Performance analysis and timing
• Error handling validation
• Automatic environment variable loading from .env file
• Requires WORDPRESS_URL, WORDPRESS_USERNAME, WORDPRESS_PASSWORD

Complete Test Report:

npm run test:summary           # Detailed project analysis

• Project overview and build status
• Tool coverage breakdown (11/11 categories)
• Configuration mode analysis
• Performance metrics and recommendations

Run All Tests:

npm run test:all               # Complete test suite

Test Results Overview

• Total Tools Tested: 124 (across all modes)
• Comprehensive Test Suite: 100% success rate ✅
• Schema Validation: 100% ✅
• Tool Categories: 11/11 covered ✅
• Configuration Modes: 4 different modes ✅
• Performance: Average 1ms validation time ✅
• Environment Variables: Automatic .env loading ✅

Project Structure

├── src/
│   ├── index.ts              # Main server implementation
│   └── server-config.ts      # Configuration system
├── dist/                     # Compiled output
├── CONFIGURATION.md          # Complete config guide
└── test-simple.js           # Configuration testing

⚡ Performance Features

Smart Data Handling

• Incremental Updates: Change individual widgets without full page reloads
• Chunked Loading: Process large pages in manageable pieces
• Element Discovery: Lightweight element ID and type listing
• Automatic Caching: Intelligent cache invalidation after updates

Memory Optimization

• Modular Loading: Only load tools you actually use
• Selective Features: Environment-based feature toggling
• Efficient Data Transfer: Minimal payloads for maximum performance

🔍 Quick Troubleshooting

⚠️ Having issues? See our comprehensive 📚 Documentation section above for complete guides.

🔐 SSL Certificate Support

The MCP server includes automatic SSL certificate handling for seamless local development:

• Local Development: Automatically allows self-signed certificates for .local, .dev, .test, localhost
• Production Sites: Requires valid SSL certificates for security
• Zero Configuration: Works out-of-the-box with popular local development tools

Quick Diagnostic Tools

// New! List all posts and pages with Elementor status
await mcp.listAllContent({ include_all_statuses: true });

// Debug specific post/page issues
await mcp.getElementorData({ post_id: 123 });

Connection Issues

# Test your WordPress connection
curl https://yoursite.com/wp-json/wp/v2/posts

Tool Count Issues

# Check your current configuration
npm run test:config

# Start with fewer tools
ELEMENTOR_MINIMAL_MODE=true npx wp-elementor-mcp

Performance Issues

• Use Essential or Standard mode for basic tasks
• Enable Advanced mode only when needed
• Use incremental updates for large pages
• Monitor tool usage and adjust configuration accordingly

Permission Errors

• Verify application password is correct
• Check WordPress user permissions
• Ensure REST API is enabled
• Test with a different user account

🛡️ Security Best Practices

• Use HTTPS for WordPress sites in production
• Rotate application passwords regularly
• Limit user permissions to minimum required
• Monitor API usage for unusual activity
• Keep WordPress and Elementor updated

📈 Migration Guide

From Previous Versions

# Old way - all tools always loaded
npx [email protected]

# New way - choose your level  
ELEMENTOR_MCP_MODE=standard npx wp-elementor-mcp

Recommended Upgrade Path

1. Start Essential: Get familiar with core features
2. Move to Standard: Add page building capabilities
3. Try Advanced: Include performance tools
4. Use Full: Only with Elementor Pro license

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Update documentation
5. Submit a pull request

Development Setup

git clone https://github.com/Huetarded/wp-elementor-mcp.git
cd wp-elementor-mcp
npm install
npm run dev  # Watch mode

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository
• Issue Tracker
• NPM Package

---

Transform your WordPress workflow with intelligent, modular MCP tools that scale with your needs!