Claudeus WordPress MCP Server

Tools are categorized by their impact on the WordPress site to help you manage risk when using AI agents or automation. Use this classification to decide whether to run operations in production or staging.

• 🟢 Safe: Read-only operations (e.g., get_posts, list_themes).
• 🟡 Moderate: Content modification (e.g., create_post, update_media).
• 🔴 High: Destructive operations (e.g., delete_post, delete_user).

You can manage multiple environments (production, staging, development) or multiple clients by defining multiple keys in your wp-sites.json file. Each key acts as a site identifier that you can reference in the Inspector UI or when prompting Claude.

{
  "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"
  }
}

To use the WordPress tools within Claude Desktop, add the server to your claude_desktop_config.json file. You must provide the absolute path to your wp-sites.json file via the WP_SITES_PATH environment variable.

File Locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

After updating the config, restart Claude Desktop completely. You should see a hammer icon in the input box indicating the 145 tools are available.

{
  "mcpServers": {
    "claudeus-wp-mcp": {
      "command": "npx",
      "args": ["-y", "claudeus-wp-mcp"],
      "env": {
        "WP_SITES_PATH": "/absolute/path/to/your/wp-sites.json"
      }
    }
  }
}

If you are developing or want to visually explore the 145 available tools, use the MCP Inspector. This launches a web UI at http://localhost:5173 where you can:

• Explore Tools: Browse all tools and their descriptions.
• Test Endpoints: Execute tools with sample data.
• View Responses: Inspect real API responses.
• Debug: Monitor server communication.
• Test Prompts: Try out AI-powered workflows.

# Launch Inspector (requires local repository clone)
pnpm inspector

To debug the MCP server, set the DEBUG environment variable to claudeus:* when running the server via Node.

# Set environment variable
export DEBUG=claudeus:*

# Run with debug enabled
WP_SITES_PATH=/path/to/wp-sites.json \
DEBUG=claudeus:* \
node dist/index.js

You can install the Claudeus WordPress MCP server globally via npm or run it directly using npx.

Prerequisites:

• Node.js ≥ 22.0.0
• pnpm (recommended) or npm
• A WordPress site with the REST API enabled
• An Application Password or JWT token for authentication

# Install globally
npm install -g claudeus-wp-mcp

# Or use directly with npx
npx claudeus-wp-mcp

To allow the MCP server to interact with your site, ensure the following:

1. REST API: Must be enabled (standard in WP 4.7+). Verify with curl https://your-site.com/wp-json/.
2. Application Passwords: Requires WordPress 5.6+ and HTTPS. Generate a password in Users → Profile.
3. Permissions: The user must have the appropriate capabilities for the tasks you want Claude to perform:
   • Posts: edit_posts, publish_posts, delete_posts
   • Pages: edit_pages, publish_pages, delete_pages
   • Media: upload_files, delete_files
   • Users: edit_users, create_users, delete_users
   • Plugins: install_plugins, activate_plugins, delete_plugins
   • Themes: switch_themes, edit_themes
   • Settings: manage_options (Administrator role covers all).

For production use with AI-powered workflows, install the MCP server globally via NPM and configure Claude Desktop to use it.

1. Install: Run npm install -g claudeus-wp-mcp.
2. Configure Sites: Create a wp-sites.json file in ~/.claudeus-mcp/ and secure it with chmod 600.
3. Update Claude Config: Edit your claude_desktop_config.json (located in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows) to include the claudeus-wp-mcp server.

Note: Use absolute paths for WP_SITES_PATH. On Windows, use forward slashes (C:/Users/...) or escaped backslashes (C:\\Users\\...).

{
  "mcpServers": {
    "claudeus-wp-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claudeus-wp-mcp"
      ],
      "env": {
        "WP_SITES_PATH": "/Users/YOUR_USERNAME/.claudeus-mcp/wp-sites.json"
      }
    }
  }
}

Use pnpm to execute the comprehensive test suite. The project provides commands for all tests, specific suites (unit and integration), and coverage reporting.

# All tests
pnpm test

# Specific suites
pnpm test:unit
pnpm test:integration

# With coverage
pnpm test:coverage

If you are developing on the project itself, follow these steps:

1. Clone & Build:
   • git clone https://github.com/deus-h/claudeus-wp-mcp
   • cd claudeus-wp-mcp
   • pnpm install
   • pnpm build
2. Configure Sites: Copy wp-sites.json.example to wp-sites.json, edit your credentials, and run chmod 600 wp-sites.json.
3. Update Claude Config: Add the server to claude_desktop_config.json using the node command pointing to the absolute path of dist/index.js and setting the WP_SITES_PATH environment variable.

{
  "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"
      }
    }
  }
}

To ensure site stability and security when using the MCP tools, follow these best practices:

1. Always Backup: Perform a full site backup before executing bulk operations.
2. Test First: Always test new workflows or AI prompts in a staging environment before production.
3. Review Changes: Manually verify any content generated or modified by AI.
4. Secure Credentials: Protect your WordPress Application Passwords and JWT tokens.
5. Monitor Usage: Track API calls and performance to ensure the MCP server is not overloading your site.