Ultimate Elementor MCP

# 🚀 Ultimate Elementor MCP - Setup Guide Complete setup instructions for all supported platforms. --- ## 📋 **Table of Contents** - [Prerequisites](#prerequisites) - [WordPress Setup](#wordpress-setup) - [MCP Installation](#mcp-installation) - [Platform-Specific Setup](#platform-specific-setup) - [Cursor](#cursor) - [Claude Desktop](#claude-desktop) - [Cline](#cline) - [Continue.dev](#continuedev) - [Other MCP Clients](#other-mcp-clients) - [Verification](#verification) - [Troubleshooting](#troubleshooting) --- ## ✅ **Prerequisites** ### **WordPress Requirements** - WordPress 5.6+ (for Application Passwords) - REST API enabled (default in WordPress) - Administrator or Editor user account - Elementor plugin installed (for Elementor features) - HTTPS recommended (required for some features) ### **System Requirements** - Node.js 18+ (only for building from source) - Git (for cloning the repository) - Text editor (for editing configuration files) ### **MCP Client** One of the following: - Cursor IDE - Claude Desktop - Cline - Continue.dev - Any MCP-compatible client --- ## 🔐 **WordPress Setup** ### **Step 1: Enable REST API** The WordPress REST API is enabled by default. Verify by visiting: ``` https://your-site.com/wp-json/ ``` You should see a JSON response. If you get a 404 error, check with your hosting provider about REST API restrictions. ### **Step 2: Create Application Password** **Important**: Use an **Application Password**, not your regular WordPress password! 1. Log into WordPress Admin 2. Go to **Users** → **Your Profile** (or **Edit Profile**) 3. Scroll down to the **Application Passwords** section 4. Enter a name: `Ultimate Elementor MCP` 5. Click **Add New Application Password** 6. **COPY THE PASSWORD IMMEDIATELY** - Format: `xxxx xxxx xxxx xxxx xxxx xxxx` **⚠️ Important Notes:** - The password is shown **only once** - Remove spaces when using it: `xxxxxxxxxxxxxxxxxxxx` - Never share this password - You can revoke it anytime from the same page ### **Step 3: Verify User Permissions** Your WordPress user should have permissions to: - ✅ Create, edit, and delete posts - ✅ Create, edit, and delete pages - ✅ Upload media files - ✅ Edit Elementor data **Recommended Role**: Administrator or Editor --- ## 📦 **MCP Installation** ### **Option 1: Clone from GitHub (Recommended)** ```bash # Clone the repository git clone https://github.com/yourusername/ultimate-elementor-mcp.git # Navigate to the directory cd ultimate-elementor-mcp # Install dependencies npm install # Build the project npm run build ``` ### **Option 2: Download ZIP** 1. Download the ZIP file from GitHub 2. Extract to your preferred location 3. Open terminal in the extracted folder 4. Run: ```bash npm install npm run build ``` ### **Verify Installation** After building, you should have: - `dist/` folder with compiled JavaScript files - `dist/index.js` as the main entry point ```bash # Check if dist folder exists ls dist/index.js # On Windows: dir dist\index.js ``` --- ## 🎯 **Platform-Specific Setup** ### **Cursor** #### **Method 1: Using Cursor Settings UI** 1. **Open Cursor Settings** - Press `Ctrl/Cmd + ,` - Or go to `File` → `Preferences` → `Settings` 2. **Find MCP Settings** - Search for "MCP" in the settings search bar - Or navigate to `Features` → `Model Context Protocol` 3. **Edit MCP Config** - Click "Edit Config" button - This opens your MCP configuration file 4. **Add Configuration** ```json { "mcpServers": { "ultimate-elementor-mcp": { "command": "node", "args": [ "C:/absolute/path/to/ultimate-elementor-mcp/dist/index.js" ], "env": { "WORDPRESS_BASE_URL": "https://your-site.com", "WORDPRESS_USERNAME": "your-username", "WORDPRESS_APPLICATION_PASSWORD": "xxxxxxxxxxxxxxxxxxxx", "MCP_MODE": "full" } } } } ``` 5. **Important Path Notes:** - **Windows**: Use forward slashes `/` or escaped backslashes `\\` - ✅ Good: `C:/Users/YourName/ultimate-elementor-mcp/dist/index.js` - ✅ Good: `C:\\Users\\YourName\\ultimate-elementor-mcp\\dist\\index.js` - ❌ Bad: `C:\Users\YourName\ultimate-elementor-mcp\dist\index.js` - **macOS/Linux**: Use standard paths - ✅ Good: `/Users/YourName/ultimate-elementor-mcp/dist/index.js` 6. **Save and Restart** - Save the configuration file - Close Cursor completely - Reopen Cursor #### **Method 2: Direct Config File Edit** **Config File Locations:** - **Windows**: `%APPDATA%\Cursor\User\globalStorage\mcp-settings.json` - **macOS**: `~/Library/Application Support/Cursor/User/globalStorage/mcp-settings.json` - **Linux**: `~/.config/Cursor/User/globalStorage/mcp-settings.json` Edit the file directly and add the same configuration as above. --- ### **Claude Desktop** 1. **Locate Config File** - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` 2. **Edit Configuration** Create or edit the file with: ```json { "mcpServers": { "ultimate-elementor-mcp": { "command": "node", "args": [ "/absolute/path/to/ultimate-elementor-mcp/dist/index.js" ], "env": { "WORDPRESS_BASE_URL": "https://your-site.com", "WORDPRESS_USERNAME": "your-username", "WORDPRESS_APPLICATION_PASSWORD": "xxxxxxxxxxxxxxxxxxxx", "MCP_MODE": "full", "DEBUG_MODE": "false" } } } } ``` 3. **Save and Restart** - Save the configuration file - Quit Claude Desktop completely - Relaunch Claude Desktop 4. **Verify Connection** - Start a new conversation - Type: "List available MCP tools" - You should see Ultimate Elementor MCP tools listed --- ### **Cline** 1. **Open Cline Settings** - Click on Cline extension settings - Find "MCP Servers" section 2. **Add MCP Server** ```json { "ultimate-elementor-mcp": { "command": "node", "args": [ "/absolute/path/to/ultimate-elementor-mcp/dist/index.js" ], "env": { "WORDPRESS_BASE_URL": "https://your-site.com", "WORDPRESS_USERNAME": "your-username", "WORDPRESS_APPLICATION_PASSWORD": "xxxxxxxxxxxxxxxxxxxx", "MCP_MODE": "full" } } } ``` 3. **Reload Extension** - Save settings - Reload VS Code window - Or restart Cline extension --- ### **Continue.dev** 1. **Open Continue Config** - Press `Ctrl/Cmd + Shift + P` - Type "Continue: Open Config" - Or edit `~/.continue/config.json` 2. **Add MCP Configuration** ```json { "mcpServers": { "ultimate-elementor-mcp": { "command": "node", "args": [ "/absolute/path/to/ultimate-elementor-mcp/dist/index.js" ], "env": { "WORDPRESS_BASE_URL": "https://your-site.com", "WORDPRESS_USERNAME": "your-username", "WORDPRESS_APPLICATION_PASSWORD": "xxxxxxxxxxxxxxxxxxxx", "MCP_MODE": "full" } } } } ``` 3. **Reload Configuration** - Save the file - Reload Continue extension - Or restart VS Code --- ### **Other MCP Clients** For any MCP-compatible client: 1. **Find MCP Configuration** - Check your client's documentation for MCP server configuration location 2. **Add Server Entry** - Command: `node` - Args: `["/absolute/path/to/dist/index.js"]` - Environment variables for WordPress credentials 3. **Standard Configuration Template** ```json { "mcpServers": { "ultimate-elementor-mcp": { "command": "node", "args": ["<ABSOLUTE_PATH_TO>/dist/index.js"], "env": { "WORDPRESS_BASE_URL": "<YOUR_SITE_URL>", "WORDPRESS_USERNAME": "<YOUR_USERNAME>", "WORDPRESS_APPLICATION_PASSWORD": "<YOUR_APP_PASSWORD>", "MCP_MODE": "full" } } } } ``` --- ## ✅ **Verification** ### **Check MCP Server is Running** 1. **Start your MCP client** (Cursor, Claude Desktop, etc.) 2. **Test basic functionality**: ``` Can you list the available MCP tools? ``` You should see tools like: - `get_posts` - `create_page` - `get_elementor_data` - `export_elementor_data` - etc. 3. **Test WordPress connection**: ``` Can you test the WordPress connection using the health_check tool? ``` 4. **Verify mode**: ``` What configuration mode is the Ultimate Elementor MCP running in? ``` ### **Expected Behavior** ✅ **Success Indicators:** - MCP tools are listed - WordPress connection succeeds - Can retrieve posts/pages - Configuration mode is displayed ❌ **Failure Indicators:** - "No MCP tools available" - Connection timeout errors - Authentication failures - Server not found errors --- ## 🔧 **Troubleshooting** ### **Problem: MCP Server Not Loading** **Symptoms**: No MCP tools available, server not found **Solutions**: 1. ✅ Verify the path is **absolute** (starts with `/` or `C:/`) 2. ✅ Check `dist/index.js` file exists 3. ✅ Run `npm run build` to ensure compilation 4. ✅ Restart your MCP client completely 5. ✅ Check client logs for error messages ### **Problem: WordPress Connection Failed** **Symptoms**: Authentication errors, 401/403 errors **Solutions**: 1. ✅ Verify WordPress URL is correct (include `https://`) 2. ✅ Check Application Password has no spaces 3. ✅ Test WordPress API: visit `https://your-site.com/wp-json/` 4. ✅ Verify user has Administrator or Editor role 5. ✅ Check hosting provider doesn't block REST API ### **Problem: Some Tools Missing** **Symptoms**: Expected tools not showing up **Solutions**: 1. ✅ Check `MCP_MODE` setting (essential/standard/advanced/full) 2. ✅ Verify WordPress credentials are set 3. ✅ Check environment variables in configuration 4. ✅ Look at server startup logs for warnings ### **Problem: File Operations Not Working** **Symptoms**: Export/import/backup operations failing **Solutions**: 1. ✅ Check `EXPORTS_DIR` and `BACKUPS_DIR` permissions 2. ✅ Ensure directories exist or can be created 3. ✅ Verify disk space is available 4. ✅ Check file system permissions ### **Problem: Elementor Data Not Loading** **Symptoms**: Empty Elementor data, no sections/widgets **Solutions**: 1. ✅ Verify Elementor plugin is installed and active 2. ✅ Check page was actually built with Elementor 3. ✅ Ensure user has permission to edit Elementor data 4. ✅ Try viewing page in Elementor editor first ### **Problem: Performance Issues** **Symptoms**: Slow responses, timeouts **Solutions**: 1. ✅ Switch to lower MCP mode (standard or essential) 2. ✅ Use chunked data retrieval for large pages 3. ✅ Enable caching in WordPress 4. ✅ Check WordPress server performance 5. ✅ Reduce `per_page` in list operations --- ## 📞 **Getting Help** If you're still experiencing issues: 1. **Check Logs** - Enable `DEBUG_MODE=true` in configuration - Check your MCP client's logs - Look for error messages in terminal/console 2. **Gather Information** - WordPress version - Elementor version - Node.js version - MCP client and version - Error messages (full text) 3. **Ask for Help** - GitHub Issues: [Create an issue](https://github.com/mbrown1837/Ultimate-Elementor-MCP/issues) - Include debug logs and configuration (remove sensitive data!) - Describe steps to reproduce the problem --- ## 🎓 **Next Steps** Now that you're set up: 1. 📖 Read the [User Guide](USER_GUIDE.md) 2. 🔧 Explore the [Tools Reference](TOOLS_REFERENCE.md) 3. 💡 Check out [Examples](EXAMPLES.md) 4. 🐛 Learn [Troubleshooting](TROUBLESHOOTING.md) --- **🔧 Ready to build amazing WordPress sites with AI!** 🚀