Troubleshooting Guide

Comprehensive troubleshooting guide for common issues with MCP WordPress Server.

🔍 Quick Diagnosis

Health Check Commands

Before diving into specific issues, run these diagnostic commands:

# Overall system health
npm run health

# Connection status
npm run status

# Test authentication
npm run test:auth

# Quick tool validation
npm run test:tools

# Performance check
npm run test:performance

Common Issue Categories

Issue Type	Symptoms	Quick Fix
Connection	Can't reach WordPress	Check URL and network
Authentication	Login failures	Verify credentials
Tools	Commands not working	Check permissions
Performance	Slow responses	Enable caching
Claude Desktop	Not appearing in Claude	Restart and reconfigure

🌐 Connection Issues

Issue: "Cannot connect to WordPress"

Symptoms:

Connection timeout errors
"Site not reachable" messages
Network-related failures

Diagnosis:

# Test WordPress REST API manually
curl -i https://your-site.com/wp-json/wp/v2/

# Should return HTTP 200 with JSON data
# If not, WordPress REST API may be disabled

Solutions:

Verify WordPress URL Format

# ✅ Correct formats
https://yoursite.com
https://www.yoursite.com
https://blog.yoursite.com

# ❌ Incorrect formats
yoursite.com          # Missing protocol
https://yoursite.com/ # Trailing slash

Check WordPress REST API
- Go to Settings → Permalinks in WordPress admin
- Click "Save Changes" to refresh rewrite rules
- Verify REST API is not disabled by plugins

Network and Firewall

# Test connectivity
ping yoursite.com

# Test HTTPS
curl -I https://yoursite.com

# Test specific port if needed
telnet yoursite.com 443

WordPress Configuration

// In wp-config.php, ensure REST API is enabled
// Remove or comment out if present:
// add_filter('rest_enabled', '__return_false');

Issue: "SSL Certificate Error"

Symptoms:

SSL verification failures
Certificate warnings

Solutions:

# For development only - disable SSL verification
export NODE_TLS_REJECT_UNAUTHORIZED=0

# Better solution: Fix SSL certificate
# Contact your hosting provider or use Let's Encrypt

🔐 Authentication Issues

Issue: "Authentication failed"

Symptoms:

401 Unauthorized errors
"Invalid credentials" messages
Login repeatedly fails

Diagnosis:

# Test authentication manually
curl -u "username:app-password" https://your-site.com/wp-json/wp/v2/users/me

# Should return user information
# If 401, credentials are wrong

Solutions:

Application Password Format

# ✅ Correct format (with spaces)
WORDPRESS_APP_PASSWORD="AbCd EfGh IjKl MnOp QrSt UvWx"

# ❌ Incorrect formats
WORDPRESS_APP_PASSWORD=AbCdEfGhIjKlMnOpQrStUvWx  # No spaces
WORDPRESS_APP_PASSWORD='AbCd EfGh...'             # Single quotes
WORDPRESS_APP_PASSWORD="AbCd-EfGh-IjKl..."       # Hyphens instead of spaces

Regenerate Application Password
- WordPress Admin → Users → Profile
- Delete old application password
- Create new one: "MCP WordPress Server"
- Copy the exact password shown (with spaces)

Check WordPress User Permissions

# Minimum role requirements:
- Read operations: Subscriber
- Create/edit posts: Author
- Manage comments: Editor
- Site settings: Administrator

Verify Application Passwords are Enabled

// In functions.php or plugin
// Ensure this is NOT present:
// add_filter('wp_is_application_passwords_available', '__return_false');

Issue: "Permission denied for operation"

Symptoms:

Some tools work, others fail
"Insufficient permissions" errors

Solutions:

Check User Role Requirements

# Test user capabilities
curl -u "username:app-password" \
  https://your-site.com/wp-json/wp/v2/users/me | \
  jq '.capabilities'

Role-Based Access Matrix | Operation | Subscriber | Author | Editor | Admin | |-----------|------------|--------|--------|-------| | Read posts | ✅ | ✅ | ✅ | ✅ | | Create posts | ❌ | ✅ | ✅ | ✅ | | Edit others' posts | ❌ | ❌ | ✅ | ✅ | | Manage users | ❌ | ❌ | ❌ | ✅ | | Site settings | ❌ | ❌ | ❌ | ✅ |

🛠️ Tool Issues

Issue: "Tool not found" or "Command failed"

Symptoms:

Specific WordPress tools don't work
"Unknown tool" errors
Tools missing from Claude

Diagnosis:

# List available tools
npm run test:tools

# Test specific tool
DEBUG=true npm run dev
# Then try the failing tool

Solutions:

Verify Tool Registration

# Check all tools are loaded
npm run status | grep "tools available"
# Should show "59 tools available"

Test Individual Tool Categories

# In Claude, test each category:
"List my WordPress posts"          # Posts tools
"Show my WordPress users"          # User tools
"Check WordPress site settings"    # Site tools
"Show cache statistics"            # Cache tools

Check Multi-Site Configuration

# If using multi-site, always specify site parameter
# ✅ Correct
wp_list_posts --site="main-site"

# ❌ Incorrect (will fail with multiple sites)
wp_list_posts

Issue: "Invalid parameters" errors

Symptoms:

Tools reject valid-looking parameters
Type validation errors

Solutions:

Check Parameter Types

# ✅ Correct parameter types
wp_create_post --title="My Post" --content="Content here"

# ❌ Incorrect (missing quotes for strings)
wp_create_post --title=My Post --content=Content here

Required vs Optional Parameters

# Check tool documentation
# Each tool specifies required parameters
# See docs/api/tools/[tool-name].md

⚡ Performance Issues

Issue: Slow response times

Symptoms:

Tools take a long time to respond
Timeout errors
Claude appears to hang

Diagnosis:

# Check performance metrics
npm run test:performance

# Test with caching disabled
DISABLE_CACHE=true npm run dev

# Monitor cache statistics
npm run cache:stats

Solutions:

Enable Caching

# Ensure caching is enabled (default)
# Remove this line if present:
# DISABLE_CACHE=true

# Check cache performance
npm run cache:stats

WordPress Optimization
- Install caching plugin (W3 Total Cache, WP Rocket)
- Optimize database and images
- Use CDN for media files
- Upgrade hosting if necessary

Network Optimization

# Test network latency
ping your-site.com

# Test WordPress response time
time curl -s https://your-site.com/wp-json/wp/v2/ > /dev/null

Issue: Memory or CPU high usage

Symptoms:

System becomes slow
High resource usage
Crashes or restarts

Solutions:

Monitor Resource Usage

# Check memory usage
npm run test:performance | grep memory

# Monitor during operation
top -p $(pgrep node)

Optimize Configuration

# Reduce cache size if memory is limited
# Edit configuration:
CACHE_MAX_SIZE=100  # Reduce from default 1000

# Disable performance monitoring in production
DISABLE_PERFORMANCE_MONITORING=true

🖥️ Claude Desktop Issues

Issue: "WordPress tools not appearing in Claude"

Symptoms:

Claude doesn't recognize WordPress commands
No WordPress functionality available
"I don't have access to WordPress" responses

Solutions:

Restart Claude Desktop

# Always restart Claude Desktop after configuration changes
# This ensures MCP server connections are refreshed

Check Configuration File

For DXT Extension:

Verify extension is enabled in Claude Desktop
Check configuration in Extensions settings
Reinstall DXT if necessary

For NPX/NPM Method:

// Verify Claude Desktop config file format
{
  "mcpServers": {
    "mcp-wordpress": {
      "command": "npx",
      "args": ["-y", "mcp-wordpress"],
      "env": {
        "WORDPRESS_SITE_URL": "https://your-site.com",
        "WORDPRESS_USERNAME": "your-username",
        "WORDPRESS_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Verify Configuration File Location

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/claude_desktop_config.json

Issue: "Server connection failed"

Symptoms:

Claude shows "MCP server connection failed"
Server appears to start but then disconnects

Solutions:

Check Server Logs

# Run server manually to see errors
DEBUG=true npx -y mcp-wordpress

# Look for specific error messages
# Common issues: missing dependencies, port conflicts

JSON-RPC Protocol Issues

# Recent fix for DXT: JSON parsing errors
# Update to latest version
curl -L -o mcp-wordpress.dxt \
  https://github.com/docdyhr/mcp-wordpress/releases/latest/download/\
  mcp-wordpress.dxt

# Reinstall DXT extension

Environment Issues

# Test Node.js version
node --version  # Should be 16+

# Test npm access
npm --version

# Clear npm cache if needed
npm cache clean --force

🐳 Docker Issues

Issue: Container won't start

Symptoms:

Docker container exits immediately
"Configuration missing" errors

Solutions:

Check Environment Variables

# Verify all required variables are set
docker run --rm docdyhr/mcp-wordpress:latest env | grep WORDPRESS

# Should show:
# WORDPRESS_SITE_URL=...
# WORDPRESS_USERNAME=...
# WORDPRESS_APP_PASSWORD=...

Check Container Logs

# View container logs
docker logs mcp-wordpress

# Follow logs in real-time
docker logs -f mcp-wordpress

Test Configuration

# Test with environment file
docker run --rm --env-file .env docdyhr/mcp-wordpress:latest npm run status

🔧 Advanced Debugging

Enable Debug Mode

Environment Variable
```
DEBUG=true npm run dev
```
For Claude Desktop DXT
- Enable "Debug Mode" in extension settings
- Check Claude Desktop console for detailed logs

Comprehensive Debugging

# Maximum debug output
NODE_ENV=development DEBUG=true LOG_LEVEL=debug npm run dev

Debug Specific Components

# Test individual components
npm run test:auth          # Authentication only
npm run test:tools         # Tool registration
npm run test:integration   # WordPress API integration
npm run test:cache         # Cache functionality
npm run test:performance   # Performance monitoring

Network Debugging

# Capture network traffic
tcpdump -i any -w capture.pcap host your-site.com

# Analyze with Wireshark or:
tcpdump -r capture.pcap -A | grep -i wordpress

WordPress Debug Mode

// Add to wp-config.php for WordPress debugging
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

// Check WordPress debug log
tail -f /path/to/wordpress/wp-content/debug.log

📋 Issue Reporting Template

When reporting issues, include this information:

### Environment

- **Installation Method**: DXT/NPX/NPM/Docker
- **Version**: [Check with npm list mcp-wordpress]
- **Node.js Version**: [node --version]
- **Operating System**: [OS and version]
- **Claude Desktop Version**: [If applicable]

### WordPress Details

- **WordPress Version**: [Check in WP admin]
- **User Role**: [Administrator/Editor/etc.]
- **Authentication Method**: [app-password/jwt/basic]
- **REST API URL**: [https://site.com/wp-json/wp/v2/]

### Issue Description

- **What you were trying to do**:
- **What happened instead**:
- **Error messages** (exact text):
- **Steps to reproduce**:

### Debug Information

```bash
# Output of diagnostic commands
npm run health
npm run status
DEBUG=true [command that failed]
```

Configuration

[Include relevant configuration, redacting sensitive information]


## 🆘 Getting Help

### Self-Help Resources

1. **[Documentation Hub](README.md)** - Complete documentation
2. **[API Reference](api/README.md)** - Tool documentation
3. **[GitHub Issues](https://github.com/docdyhr/mcp-wordpress/issues)** - Known issues and solutions

### Community Support

1. **[GitHub Discussions](https://github.com/docdyhr/mcp-wordpress/discussions)** - Community Q&A
2. **[Issue Tracker](https://github.com/docdyhr/mcp-wordpress/issues/new)** - Bug reports

### Professional Support

For enterprise users or complex integrations:
- Priority support available
- Custom configuration assistance
- Integration consulting

---

**Still having issues?** [Open a GitHub issue](https://github.com/docdyhr/mcp-wordpress/issues/new) with the debugging information above, and we'll help you resolve it!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Troubleshooting Guide

🔍 Quick Diagnosis

Health Check Commands

Common Issue Categories

🌐 Connection Issues

Issue: "Cannot connect to WordPress"

Issue: "SSL Certificate Error"

🔐 Authentication Issues

Issue: "Authentication failed"

Issue: "Permission denied for operation"

🛠️ Tool Issues

Issue: "Tool not found" or "Command failed"

Issue: "Invalid parameters" errors

⚡ Performance Issues

Issue: Slow response times

Issue: Memory or CPU high usage

🖥️ Claude Desktop Issues

Issue: "WordPress tools not appearing in Claude"

Issue: "Server connection failed"

🐳 Docker Issues

Issue: Container won't start

🔧 Advanced Debugging

Enable Debug Mode

Debug Specific Components

Network Debugging

WordPress Debug Mode

📋 Issue Reporting Template

Configuration

Uh oh!

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting Guide

🔍 Quick Diagnosis

Health Check Commands

Common Issue Categories

🌐 Connection Issues

Issue: "Cannot connect to WordPress"

Issue: "SSL Certificate Error"

🔐 Authentication Issues

Issue: "Authentication failed"

Issue: "Permission denied for operation"

🛠️ Tool Issues

Issue: "Tool not found" or "Command failed"

Issue: "Invalid parameters" errors

⚡ Performance Issues

Issue: Slow response times

Issue: Memory or CPU high usage

🖥️ Claude Desktop Issues

Issue: "WordPress tools not appearing in Claude"

Issue: "Server connection failed"

🐳 Docker Issues

Issue: Container won't start

🔧 Advanced Debugging

Enable Debug Mode

Debug Specific Components

Network Debugging

WordPress Debug Mode

📋 Issue Reporting Template

Configuration