SETUP-GUIDE.md•16.5 kB
# 🤘 Claudeus WordPress MCP - Complete Setup Guide
**Get your 145-tool WordPress powerhouse running in minutes!** 🔥
---
## 📋 Table of Contents
1. [Quick Start (Inspector UI)](#-quick-start-inspector-ui)
2. [Claude Desktop Setup](#-claude-desktop-setup)
3. [WordPress Configuration](#-wordpress-configuration)
4. [Multi-Site Setup](#-multi-site-setup)
5. [Environment Variables](#-environment-variables)
6. [Testing & Verification](#-testing--verification)
7. [Advanced Configuration](#-advanced-configuration)
8. [Troubleshooting](#-troubleshooting)
---
## 🚀 Quick Start (Inspector UI)
**Best for:** Testing, development, and exploring all 145 tools
### Step 1: Configure WordPress Site
Create `wp-sites.json` in the project root:
```json
{
"default_test": {
"URL": "https://your-wordpress-site.com",
"USER": "admin",
"PASS": "your-application-password",
"authType": "basic"
}
}
```
### Step 2: Get Application Password
1. Log into WordPress Admin
2. Navigate to **Users → Profile**
3. Scroll to **"Application Passwords"** section
4. Enter name: `"Claude MCP"`
5. Click **"Add New"**
6. Copy the generated password
- Format: `xxxx xxxx xxxx xxxx xxxx xxxx`
- Use as-is with spaces
### Step 3: Launch Inspector
```bash
# From project root
pnpm inspector
# Inspector opens at http://localhost:5173
```
**What happens automatically:**
- ✅ Project builds
- ✅ Inspector UI launches
- ✅ `WP_SITES_PATH` pre-filled
- ✅ Ready to connect!
### Step 4: Test Connection
1. Click **"Connect"** in Inspector
2. Go to **"Tools"** tab
3. You should see all 145 tools listed
4. Try: `claudeus_wp_discover_endpoints`
```json
{
"site": "default_test"
}
```
5. Success! You'll see available WordPress endpoints
---
## 🎸 Claude Desktop Setup
**Best for:** Production use with AI-powered workflows
### Prerequisites
- ✅ Node.js ≥ 22.0.0
- ✅ Claude Desktop installed ([Mac](https://storage.googleapis.com/osprey-downloads-c02f6a0d-347c-492b-a752-3e0651722e97/nest/Claude.dmg) | [Windows](https://storage.googleapis.com/osprey-downloads-c02f6a0d-347c-492b-a752-3e0651722e97/nest-win-x64/Claude-Setup-x64.exe))
- ✅ WordPress site with REST API enabled
- ✅ Application password generated
### Option 1: NPM Installation (Recommended)
#### Step 1: Install MCP Server
```bash
# Install globally
npm install -g claudeus-wp-mcp
# Or use npx (no installation needed)
# Configure in claude_desktop_config.json with npx command
```
#### Step 2: Create wp-sites.json
Create your sites configuration file:
```bash
# Create directory for config
mkdir -p ~/.claudeus-mcp
# Create wp-sites.json
cat > ~/.claudeus-mcp/wp-sites.json << 'EOF'
{
"default_test": {
"URL": "https://your-site.com",
"USER": "admin",
"PASS": "xxxx xxxx xxxx xxxx xxxx xxxx",
"authType": "basic"
}
}
EOF
# Secure the file
chmod 600 ~/.claudeus-mcp/wp-sites.json
```
#### Step 3: Configure Claude Desktop
**Find config file:**
| OS | Location |
|----|----------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
**Or open via Claude Desktop:**
- Claude menu → Settings → Developer → Edit Config
**Add configuration:**
```json
{
"mcpServers": {
"claudeus-wp-mcp": {
"command": "npx",
"args": [
"-y",
"claudeus-wp-mcp"
],
"env": {
"WP_SITES_PATH": "/Users/YOUR_USERNAME/.claudeus-mcp/wp-sites.json"
}
}
}
}
```
**⚠️ Important:**
- Replace `/Users/YOUR_USERNAME/` with your actual home directory
- Use absolute paths (not `~` or relative paths)
- On Windows, use forward slashes: `C:/Users/...` or escape backslashes: `C:\\Users\\...`
### Option 2: Local Development Setup
#### Step 1: Clone & Build
```bash
# Clone repository
git clone https://github.com/deus-h/claudeus-wp-mcp
cd claudeus-wp-mcp
# Install dependencies
pnpm install
# Build project
pnpm build
```
#### Step 2: Configure wp-sites.json
```bash
# Copy example
cp wp-sites.json.example wp-sites.json
# Edit with your credentials
nano wp-sites.json
# Secure the file
chmod 600 wp-sites.json
```
#### Step 3: Configure Claude Desktop
```json
{
"mcpServers": {
"claudeus-wordpress": {
"command": "node",
"args": [
"/absolute/path/to/claudeus-wp-mcp/dist/index.js"
],
"env": {
"WP_SITES_PATH": "/absolute/path/to/claudeus-wp-mcp/wp-sites.json"
}
}
}
}
```
### Step 4: Restart & Test
1. **Completely quit Claude Desktop**
- macOS: `Cmd + Q`
- Windows: Right-click taskbar → Quit
2. **Restart Claude Desktop**
3. **Look for hammer icon (🔨)** in chat input
4. **Test with Claude:**
```
"Can you show me what WordPress tools are available?"
```
5. **Success indicators:**
- Hammer icon appears
- Claude lists tools
- Can execute WordPress operations
---
## 🌐 WordPress Configuration
### Enable REST API
WordPress REST API is enabled by default since version 4.7. Verify it's working:
```bash
# Test REST API (replace with your URL)
curl https://your-site.com/wp-json/
# Should return JSON with routes
```
### Application Passwords
**Requirements:**
- WordPress 5.6+
- HTTPS enabled (required for application passwords)
- User with appropriate capabilities
**Creating Application Password:**
1. **Log into WordPress Admin**
2. **Users → Profile**
3. **Scroll to "Application Passwords"**
4. **Enter name:** `Claude MCP` (or any identifier)
5. **Click "Add New"**
6. **Copy password:** Includes spaces - use as-is!
**Security Best Practices:**
- ✅ One password per application
- ✅ Use descriptive names
- ✅ Revoke when not needed
- ✅ Never commit to version control
- ✅ Use different passwords per environment
### Verify Permissions
Ensure your WordPress user has required capabilities:
| Operation | Required Capability |
|-----------|-------------------|
| Manage Posts | `edit_posts`, `publish_posts`, `delete_posts` |
| Manage Pages | `edit_pages`, `publish_pages`, `delete_pages` |
| Manage Media | `upload_files`, `delete_files` |
| Manage Users | `edit_users`, `create_users`, `delete_users` |
| Manage Plugins | `install_plugins`, `activate_plugins`, `delete_plugins` |
| Manage Themes | `switch_themes`, `edit_themes` |
| Site Settings | `manage_options` |
**Administrator role has all capabilities** - recommended for full access.
---
## 🎯 Multi-Site Setup
Manage multiple WordPress sites with a single configuration:
### Basic Multi-Site Configuration
```json
{
"production": {
"URL": "https://live-site.com",
"USER": "admin",
"PASS": "prod-password-here",
"authType": "basic"
},
"staging": {
"URL": "https://staging-site.com",
"USER": "admin",
"PASS": "stage-password-here",
"authType": "basic"
},
"development": {
"URL": "https://dev-site.local",
"USER": "admin",
"PASS": "dev-password-here",
"authType": "basic"
}
}
```
### Multi-Client Configuration
```json
{
"client1_prod": {
"URL": "https://client1-live.com",
"USER": "admin",
"PASS": "xxxx xxxx xxxx xxxx",
"authType": "basic"
},
"client1_stage": {
"URL": "https://client1-staging.com",
"USER": "admin",
"PASS": "yyyy yyyy yyyy yyyy",
"authType": "basic"
},
"client2_prod": {
"URL": "https://client2-live.com",
"USER": "admin",
"PASS": "zzzz zzzz zzzz zzzz",
"authType": "basic"
}
}
```
### Using Multiple Sites
**In Inspector UI:**
```json
{
"site": "production" // or "staging", "client1_prod", etc.
}
```
**With Claude:**
```
"Create a blog post on the staging site about..."
"List all posts from client1_prod"
"Check health status for production"
```
---
## 🔧 Environment Variables
### Required Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `WP_SITES_PATH` | Path to wp-sites.json | `/path/to/wp-sites.json` |
### Optional Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `NODE_ENV` | Environment mode | `production` |
| `LOG_LEVEL` | Logging verbosity | `info` |
| `DEBUG` | Enable debug mode | `false` |
### Setting Environment Variables
**macOS/Linux:**
```bash
# Temporary (current session)
export WP_SITES_PATH="/path/to/wp-sites.json"
# Permanent (add to ~/.zshrc or ~/.bashrc)
echo 'export WP_SITES_PATH="/path/to/wp-sites.json"' >> ~/.zshrc
source ~/.zshrc
```
**Windows (PowerShell):**
```powershell
# Temporary (current session)
$env:WP_SITES_PATH = "C:\path\to\wp-sites.json"
# Permanent (System Environment Variables)
[System.Environment]::SetEnvironmentVariable("WP_SITES_PATH", "C:\path\to\wp-sites.json", "User")
```
---
## ✅ Testing & Verification
### Test Checklist
#### 1. Connection Test
```bash
# Test with Inspector
pnpm inspector
# Or test REST API directly
curl https://your-site.com/wp-json/wp/v2/
```
#### 2. Authentication Test
**In Inspector, run:**
```json
Tool: claudeus_wp_health__test_auth
Arguments: { "site": "default_test" }
```
**Expected response:**
```json
{
"status": "good",
"label": "Authorization header test",
"description": "The REST API can use the Authorization header..."
}
```
#### 3. Tools Discovery Test
**Run:**
```json
Tool: claudeus_wp_discover_endpoints
Arguments: { "site": "default_test" }
```
**Expected:** JSON with all available WordPress endpoints
#### 4. Content Read Test
**Run:**
```json
Tool: claudeus_wp_content__get_posts
Arguments: {
"site": "default_test",
"filters": {
"per_page": 5
}
}
```
**Expected:** List of posts with pagination metadata
#### 5. Health Check Test
**Run:**
```json
Tool: claudeus_wp_health__run_all_tests
Arguments: { "site": "default_test" }
```
**Expected:** Comprehensive health report
### Verification Script
Create `test-connection.sh`:
```bash
#!/bin/bash
echo "🧪 Testing Claudeus WordPress MCP..."
# Test 1: REST API Availability
echo "1️⃣ Testing REST API..."
curl -s https://your-site.com/wp-json/ > /dev/null && echo "✅ REST API accessible" || echo "❌ REST API unreachable"
# Test 2: Inspector Launch
echo "2️⃣ Testing Inspector..."
pnpm inspector &
sleep 5
curl -s http://localhost:5173 > /dev/null && echo "✅ Inspector running" || echo "❌ Inspector failed"
# Test 3: Build Status
echo "3️⃣ Testing Build..."
[ -f "dist/index.js" ] && echo "✅ Build complete" || echo "❌ Build missing"
echo "✅ Tests complete!"
```
---
## ⚙️ Advanced Configuration
### Site-Specific Capabilities
Restrict dangerous operations per site:
```json
{
"production": {
"URL": "https://live-site.com",
"USER": "admin",
"PASS": "xxxx xxxx xxxx xxxx",
"authType": "basic",
"capabilities": {
"content": {
"claudeus_wp_content__delete_post": false,
"claudeus_wp_content__delete_page": false,
"claudeus_wp_content__delete_block": false
},
"media": {
"claudeus_wp_media__delete": false
},
"users": {
"claudeus_wp_users__delete_user": false
},
"plugins": {
"claudeus_wp_plugins__delete": false
},
"themes": {
"claudeus_wp_theme__activate": false
}
}
}
}
```
**Effect:** Production site becomes read/write only - no destructive operations.
### JWT Authentication
For sites using JWT authentication:
```json
{
"jwt_site": {
"URL": "https://jwt-site.com",
"USER": "admin",
"PASS": "your-jwt-token",
"authType": "jwt"
}
}
```
**JWT Token Setup:**
1. Install [JWT Authentication plugin](https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api/)
2. Configure plugin
3. Generate token
4. Use token as `PASS` value
### Custom Headers
Add custom headers for specific sites:
```json
{
"custom_site": {
"URL": "https://custom-site.com",
"USER": "admin",
"PASS": "xxxx xxxx xxxx xxxx",
"authType": "basic",
"headers": {
"X-Custom-Header": "custom-value",
"X-API-Version": "v2"
}
}
}
```
---
## 🔍 Troubleshooting
### Common Issues & Solutions
#### Issue 1: "Connection Failed"
**Symptoms:**
- Inspector won't connect
- Claude Desktop shows no tools
**Solutions:**
1. **Verify wp-sites.json path is absolute**
```bash
# Check file exists
ls -la /absolute/path/to/wp-sites.json
```
2. **Test WordPress REST API**
```bash
curl https://your-site.com/wp-json/
```
3. **Verify Application Password**
- Check for typos
- Ensure spaces are included
- Try generating new password
4. **Check HTTPS**
- Application Passwords require HTTPS
- Test: Visit site with https://
#### Issue 2: "Authorization Failed"
**Symptoms:**
- `401 Unauthorized` errors
- "Authorization header test failed"
**Solutions:**
1. **Regenerate Application Password**
- WordPress Admin → Users → Profile
- Delete old password
- Create new one
2. **Check User Capabilities**
- Ensure user has required permissions
- Try with Administrator role
3. **Verify REST API Authentication**
```bash
curl -u admin:xxxx-xxxx-xxxx-xxxx \
https://your-site.com/wp-json/wp/v2/users/me
```
#### Issue 3: "Tools Not Showing in Claude Desktop"
**Symptoms:**
- No hammer icon
- Tools list empty
**Solutions:**
1. **Verify Config Syntax**
```bash
# Validate JSON
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
```
2. **Check Paths Are Absolute**
```json
// ❌ Wrong
"WP_SITES_PATH": "~/wp-sites.json"
// ✅ Correct
"WP_SITES_PATH": "/Users/yourname/wp-sites.json"
```
3. **Completely Restart Claude**
- Not just reload - full quit and restart
- macOS: `Cmd + Q` then relaunch
4. **Check Claude Logs**
```bash
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log
# Look for errors or connection issues
```
#### Issue 4: "Some Tools Fail, Others Work"
**Symptoms:**
- Some tools return errors
- Others work fine
**Solutions:**
1. **Check Tool-Specific Requirements**
- FSE tools require WordPress 5.9+
- Astra tools require Astra theme installed
- WooCommerce tools require WooCommerce plugin
2. **Verify Plugin/Theme Active**
```json
Tool: claudeus_wp_plugins__list
Tool: claudeus_wp_theme__list
```
3. **Check User Capabilities**
- Different tools require different permissions
- Administrator role recommended
#### Issue 5: "Performance Issues / Timeouts"
**Symptoms:**
- Slow responses
- Timeout errors
- Bulk operations fail
**Solutions:**
1. **Use Pagination**
```json
{
"filters": {
"per_page": 10, // Smaller batches
"page": 1
}
}
```
2. **Check WordPress Performance**
```json
Tool: claudeus_wp_health__run_all_tests
```
3. **Verify Server Resources**
- Check WordPress hosting limits
- Monitor PHP memory limit
- Check WordPress debug log
### Debug Mode
Enable debug logging:
```bash
# Set environment variable
export DEBUG=claudeus:*
# Run with debug enabled
WP_SITES_PATH=/path/to/wp-sites.json \
DEBUG=claudeus:* \
node dist/index.js
```
### Getting Help
**Before Reporting Issues:**
1. ✅ Check this guide
2. ✅ Review [SECURITY.md](SECURITY.md)
3. ✅ Test with Inspector UI
4. ✅ Check Claude Desktop logs
5. ✅ Verify WordPress REST API works
**Team Members:**
- 📧 Email: deus.h@outlook.com
- 🔧 Internal: Slack #claudeus-mcp channel
---
## 📚 Quick Reference
### Essential Commands
```bash
# Install
npm install -g claudeus-wp-mcp
# Launch Inspector
pnpm inspector
# Build project
pnpm build
# Run tests
pnpm test
# Watch mode
pnpm watch
```
### Essential Paths
| OS | Config Location |
|----|----------------|
| macOS | `~/Library/Application Support/Claude/` |
| Windows | `%APPDATA%\Claude\` |
### Essential Files
| File | Purpose |
|------|---------|
| `wp-sites.json` | Site configuration |
| `claude_desktop_config.json` | Claude Desktop config |
| `dist/index.js` | Built MCP server |
---
## 🎯 Next Steps
After successful setup:
1. **📖 Explore Tools** - Try all 145 tools in Inspector
2. **🔒 Review Security** - Read [SECURITY.md](SECURITY.md)
3. **🎸 Start Creating** - Use with Claude for AI-powered workflows
4. **📊 Monitor Health** - Run regular health checks
5. **🚀 Automate** - Build custom workflows
---
> 🤘 **Setup complete! You now have 145 WordPress tools at your command!**
Made with 🤘🔥 by Deusware AB