Skip to content

CONFIGURATION.md

Latest commit

 

History

History
690 lines (542 loc) · 16.1 KB

CONFIGURATION.md

File metadata and controls

690 lines (542 loc) · 16.1 KB

Configuration Guide

Complete configuration reference for MCP WordPress Server supporting single-site and multi-site deployments.

🎯 Configuration Overview

The MCP WordPress Server supports flexible configuration through multiple methods:

Method Best For Configuration File
Environment Variables Single site, development .env
Multi-Site JSON Multiple sites, production mcp-wordpress.config.json
Claude Desktop Desktop integration claude_desktop_config.json
DXT Extension Easy desktop setup Built-in UI

🌐 Single-Site Configuration

Environment Variables

Create a .env file in your project root:

# WordPress Connection (Required)
WORDPRESS_SITE_URL=https://your-site.com
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx

# Authentication Method (Optional)
WORDPRESS_AUTH_METHOD=app-password

# Environment Settings (Optional)
NODE_ENV=production
DEBUG=false
LOG_LEVEL=info

# Performance Settings (Optional)
DISABLE_CACHE=false
CACHE_TTL=300
MAX_CACHE_SIZE=1000

# Security Settings (Optional)
RATE_LIMIT_REQUESTS=1000
RATE_LIMIT_WINDOW=60000

Environment Variable Reference

Required Variables

Variable Required Description Example
WORDPRESS_SITE_URL Yes Full WordPress site URL https://blog.example.com
WORDPRESS_USERNAME Yes WordPress username admin
WORDPRESS_APP_PASSWORD Yes WordPress application password AbCd EfGh IjKl MnOp QrSt UvWx

Authentication Variables

Variable Default Description Options
WORDPRESS_AUTH_METHOD app-password Authentication method app-password, jwt, basic, api-key

Runtime Variables

Variable Default Description Options
NODE_ENV production Runtime environment development, production, test, dxt
DEBUG false Enable debug logging true, false
LOG_LEVEL info Logging verbosity error, warn, info, debug

Performance Variables

Variable Default Description Range
DISABLE_CACHE false Disable caching system true, false
CACHE_TTL 300 Cache time-to-live (seconds) 60-3600
MAX_CACHE_SIZE 1000 Maximum cache entries 100-10000

🏢 Multi-Site Configuration

Configuration File Structure

Create mcp-wordpress.config.json in your project root:

{
  "sites": [
    {
      "id": "main-site",
      "name": "Main WordPress Site",
      "config": {
        "WORDPRESS_SITE_URL": "https://main-site.com",
        "WORDPRESS_USERNAME": "admin",
        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
        "WORDPRESS_AUTH_METHOD": "app-password"
      }
    },
    {
      "id": "client-blog",
      "name": "Client Blog",
      "config": {
        "WORDPRESS_SITE_URL": "https://client-blog.com",
        "WORDPRESS_USERNAME": "editor",
        "WORDPRESS_APP_PASSWORD": "yyyy yyyy yyyy yyyy yyyy yyyy",
        "WORDPRESS_AUTH_METHOD": "jwt"
      }
    },
    {
      "id": "dev-site",
      "name": "Development Site",
      "config": {
        "WORDPRESS_SITE_URL": "https://dev.example.com",
        "WORDPRESS_USERNAME": "developer",
        "WORDPRESS_APP_PASSWORD": "zzzz zzzz zzzz zzzz zzzz zzzz",
        "WORDPRESS_AUTH_METHOD": "basic"
      }
    }
  ]
}

Multi-Site Configuration Rules

Site Identification

  • id: Unique identifier (alphanumeric, hyphens, underscores only)
  • name: Human-readable name for documentation
  • Maximum sites: 50 sites per configuration

Uniqueness Requirements

All of these must be unique across all sites:

  • Site IDs
  • Site names
  • WordPress site URLs

Site-Specific Usage

# Target specific site with --site parameter
wp_list_posts --site="main-site"
wp_create_post --site="client-blog" --title="New Post"
wp_get_site_settings --site="dev-site"

# If only one site configured, --site parameter is optional
# If multiple sites configured, --site parameter is required

Multi-Site Example Configurations

Agency Setup

{
  "sites": [
    {
      "id": "agency-main",
      "name": "Agency Main Website",
      "config": {
        "WORDPRESS_SITE_URL": "https://agency.com",
        "WORDPRESS_USERNAME": "admin",
        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    },
    {
      "id": "client-a",
      "name": "Client A Blog",
      "config": {
        "WORDPRESS_SITE_URL": "https://clienta.com/blog",
        "WORDPRESS_USERNAME": "editor",
        "WORDPRESS_APP_PASSWORD": "yyyy yyyy yyyy yyyy yyyy yyyy"
      }
    },
    {
      "id": "client-b",
      "name": "Client B E-commerce",
      "config": {
        "WORDPRESS_SITE_URL": "https://clientb-shop.com",
        "WORDPRESS_USERNAME": "shop_manager",
        "WORDPRESS_APP_PASSWORD": "zzzz zzzz zzzz zzzz zzzz zzzz"
      }
    }
  ]
}

Development Workflow

{
  "sites": [
    {
      "id": "production",
      "name": "Production Site",
      "config": {
        "WORDPRESS_SITE_URL": "https://mysite.com",
        "WORDPRESS_USERNAME": "admin",
        "WORDPRESS_APP_PASSWORD": "prod prod prod prod prod prod"
      }
    },
    {
      "id": "staging",
      "name": "Staging Environment",
      "config": {
        "WORDPRESS_SITE_URL": "https://staging.mysite.com",
        "WORDPRESS_USERNAME": "admin",
        "WORDPRESS_APP_PASSWORD": "stag stag stag stag stag stag"
      }
    },
    {
      "id": "local",
      "name": "Local Development",
      "config": {
        "WORDPRESS_SITE_URL": "http://localhost:8080",
        "WORDPRESS_USERNAME": "dev",
        "WORDPRESS_APP_PASSWORD": "locl locl locl locl locl locl",
        "WORDPRESS_AUTH_METHOD": "basic"
      }
    }
  ]
}

🔐 Authentication Configuration

Application Passwords (Recommended)

WordPress Setup:

  1. Enable Application Passwords (WordPress 5.6+)
  2. Generate Password: Users → Profile → Application Passwords
  3. Copy Password: Exact format with spaces

Configuration:

{
  "WORDPRESS_AUTH_METHOD": "app-password",
  "WORDPRESS_USERNAME": "your-username",
  "WORDPRESS_APP_PASSWORD": "AbCd EfGh IjKl MnOp QrSt UvWx"
}

Security Benefits:

  • ✅ Revocable without changing main password
  • ✅ Scoped permissions
  • ✅ Audit trail
  • ✅ WordPress native support

JWT Authentication

WordPress Setup:

  1. Install JWT Plugin: JWT Authentication for WP-API
  2. Configure JWT Secret in wp-config.php
  3. Get JWT Token via login endpoint

Configuration:

{
  "WORDPRESS_AUTH_METHOD": "jwt",
  "WORDPRESS_USERNAME": "your-username",
  "WORDPRESS_APP_PASSWORD": "your-jwt-token"
}

WordPress JWT Setup:

// wp-config.php
define('JWT_AUTH_SECRET_KEY', 'your-secret-key');
define('JWT_AUTH_CORS_ENABLE', true);

Basic Authentication

⚠️ Development Only - Not recommended for production

Configuration:

{
  "WORDPRESS_AUTH_METHOD": "basic",
  "WORDPRESS_USERNAME": "your-username",
  "WORDPRESS_APP_PASSWORD": "your-regular-password"
}

API Key Authentication

WordPress Setup:

  1. Install API Key Plugin
  2. Generate API Key in WordPress admin
  3. Configure Key Permissions

Configuration:

{
  "WORDPRESS_AUTH_METHOD": "api-key",
  "WORDPRESS_USERNAME": "your-username",
  "WORDPRESS_APP_PASSWORD": "your-api-key"
}

⚙️ Claude Desktop Configuration

NPX Method

Add to claude_desktop_config.json:

{
  "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",
        "WORDPRESS_AUTH_METHOD": "app-password"
      }
    }
  }
}

NPM Global Method

{
  "mcpServers": {
    "mcp-wordpress": {
      "command": "mcp-wordpress",
      "env": {
        "WORDPRESS_SITE_URL": "https://your-site.com",
        "WORDPRESS_USERNAME": "your-username",
        "WORDPRESS_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Multi-Site in Claude Desktop

For multi-site setups, create a configuration file and reference it:

{
  "mcpServers": {
    "mcp-wordpress": {
      "command": "npx",
      "args": ["-y", "mcp-wordpress"],
      "cwd": "/path/to/your/config/directory"
    }
  }
}

🐳 Docker Configuration

Docker Environment Setup

# Single site
docker run -d \
  --name mcp-wordpress \
  -e WORDPRESS_SITE_URL=https://your-site.com \
  -e WORDPRESS_USERNAME=your-username \
  -e WORDPRESS_APP_PASSWORD="your app password" \
  docdyhr/mcp-wordpress:latest

Docker Compose

version: "3.8"
services:
  mcp-wordpress:
    image: docdyhr/mcp-wordpress:latest
    environment:
      WORDPRESS_SITE_URL: https://your-site.com
      WORDPRESS_USERNAME: your-username
      WORDPRESS_APP_PASSWORD: your app password
      WORDPRESS_AUTH_METHOD: app-password
      DEBUG: "false"
    volumes:
      - ./config:/app/config
    restart: unless-stopped

Multi-Site with Docker

version: "3.8"
services:
  mcp-wordpress:
    image: docdyhr/mcp-wordpress:latest
    volumes:
      - ./mcp-wordpress.config.json:/app/mcp-wordpress.config.json:ro
    restart: unless-stopped

🔧 Advanced Configuration

Performance Tuning

Cache Configuration

# Optimize for high-traffic sites
CACHE_TTL=600              # 10 minutes
MAX_CACHE_SIZE=5000        # 5000 entries
CACHE_CLEANUP_INTERVAL=300 # 5 minutes

# Optimize for low-memory environments
CACHE_TTL=120              # 2 minutes
MAX_CACHE_SIZE=100         # 100 entries
DISABLE_CACHE=false        # Keep basic caching

Rate Limiting

# Conservative limits
RATE_LIMIT_REQUESTS=100    # 100 requests
RATE_LIMIT_WINDOW=60000    # per minute

# Aggressive limits
RATE_LIMIT_REQUESTS=1000   # 1000 requests
RATE_LIMIT_WINDOW=60000    # per minute

Security Hardening

Network Security

# Bind to specific interface (Docker/production)
BIND_ADDRESS=127.0.0.1
PORT=3000

# SSL/TLS Configuration
SSL_CERT=/path/to/cert.pem
SSL_KEY=/path/to/key.pem
FORCE_HTTPS=true

Authentication Security

# Strengthen authentication
AUTH_TIMEOUT=300           # 5 minute auth timeout
MAX_AUTH_ATTEMPTS=3        # Max failed attempts
AUTH_LOCKOUT_DURATION=900  # 15 minute lockout

Monitoring Configuration

Logging

# Development logging
NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug

# Production logging
NODE_ENV=production
DEBUG=false
LOG_LEVEL=warn
LOG_FILE=/var/log/mcp-wordpress.log

Performance Monitoring

# Enable performance tracking
ENABLE_PERFORMANCE_MONITORING=true
PERFORMANCE_SAMPLE_RATE=0.1  # 10% sampling
METRICS_ENDPOINT=/metrics

# Disable in resource-constrained environments
ENABLE_PERFORMANCE_MONITORING=false

✅ Configuration Validation

Validation Commands

# Validate current configuration
npm run config:validate

# Test specific site (multi-site)
npm run config:test --site="site-id"

# Validate and show configuration
npm run config:show

Common Validation Errors

1. Invalid URL Format

# ❌ Common mistakes
WORDPRESS_SITE_URL=mysite.com           # Missing protocol
WORDPRESS_SITE_URL=https://mysite.com/  # Trailing slash
WORDPRESS_SITE_URL=http://localhost     # Missing port for local

# ✅ Correct formats
WORDPRESS_SITE_URL=https://mysite.com
WORDPRESS_SITE_URL=http://localhost:8080
WORDPRESS_SITE_URL=https://blog.mysite.com

2. Invalid Authentication Method

# ❌ Invalid
WORDPRESS_AUTH_METHOD=password          # Not supported

# ✅ Valid options
WORDPRESS_AUTH_METHOD=app-password       # Recommended
WORDPRESS_AUTH_METHOD=jwt               # With plugin
WORDPRESS_AUTH_METHOD=basic             # Development only
WORDPRESS_AUTH_METHOD=api-key           # With plugin

3. Multi-Site Configuration Errors

# ❌ Duplicate site IDs
{"id": "site1", ...}
{"id": "site1", ...}  # Error: duplicate ID

# ❌ Invalid site ID characters
{"id": "site 1", ...}      # Spaces not allowed
{"id": "site@1", ...}      # Special chars not allowed

# ✅ Valid site IDs
{"id": "site-1", ...}      # Hyphens OK
{"id": "site_1", ...}      # Underscores OK
{"id": "site1", ...}       # Alphanumeric OK

🔄 Configuration Migration

From Single-Site to Multi-Site

  1. Backup Current Configuration

    cp .env .env.backup

  2. Create Multi-Site Config

    {
  "sites": [
    {
      "id": "default",
      "name": "Main Site",
      "config": {
        "WORDPRESS_SITE_URL": "your-current-url",
        "WORDPRESS_USERNAME": "your-current-username",
        "WORDPRESS_APP_PASSWORD": "your-current-password"
      }
    }
  ]
}

  3. Update Claude Desktop Config

    {
  "mcpServers": {
    "mcp-wordpress": {
      "command": "npx",
      "args": ["-y", "mcp-wordpress"],
      "cwd": "/path/to/config/directory"
    }
  }
}

From Multi-Site to Single-Site

  1. Choose Primary Site from multi-site config

  2. Extract Configuration

    # From mcp-wordpress.config.json site
WORDPRESS_SITE_URL=https://primary-site.com
WORDPRESS_USERNAME=primary-username
WORDPRESS_APP_PASSWORD=primary-password

  3. Update Environment and remove config file

🛡️ Security Best Practices

Credential Management

  1. Never commit credentials to version control

    # Add to .gitignore
.env
mcp-wordpress.config.json
claude_desktop_config.json

  2. Use Application Passwords instead of main passwords

  3. Rotate credentials regularly

  4. Use minimal permissions for WordPress users

  5. Monitor authentication logs

Configuration Security

  1. File Permissions

    # Secure configuration files
chmod 600 .env
chmod 600 mcp-wordpress.config.json

  2. Environment Isolation

    # Separate configs for different environments
.env.development
.env.staging
.env.production

  3. Secrets Management

    # Use secrets management for production
# Examples: AWS Secrets Manager, HashiCorp Vault

📚 Configuration Examples

Example Templates

Complete configuration examples are available in:

Production Configuration

# Production best practices
NODE_ENV=production
DEBUG=false
LOG_LEVEL=warn
WORDPRESS_AUTH_METHOD=app-password
DISABLE_CACHE=false
CACHE_TTL=600
RATE_LIMIT_REQUESTS=1000

Development Configuration

# Development best practices
NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug
WORDPRESS_AUTH_METHOD=app-password
DISABLE_CACHE=false
CACHE_TTL=60

Need help with configuration? Check the Troubleshooting Guide or open an issue for assistance.