Mainwp Mcp

MainWP MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to manage WordPress sites through the MainWP Dashboard REST API.

Table of Contents

• [Overview](#overview)
• [Features](#features)
• [Architecture](#architecture)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [MainWP Dashboard Setup](#mainwp-dashboard-setup)
• [Configuration](#configuration)
• [Claude Code Integration](#claude-code-integration)
• [Available Tools](#available-tools)
• [Usage Examples](#usage-examples)
• [Safety Features](#safety-features)
• [Troubleshooting](#troubleshooting)
• [Development](#development)
• [API Reference](#api-reference)
• [Contributing](#contributing)
• [License](#license)

---

Overview

MainWP MCP Server bridges the gap between AI assistants and WordPress site management. It allows Claude (via Claude Code) to:

• Monitor the health and status of all your WordPress sites
• Check for and apply updates to WordPress core, plugins, and themes
• Manage plugins and themes across single or multiple sites
• Add, sync, and manage sites in your MainWP Dashboard

This is particularly useful for agencies, freelancers, or anyone managing multiple WordPress sites who wants to leverage AI assistance for routine maintenance tasks.

---

Features

43 tools covering the complete MainWP REST API:

Site Management (14 tools)

• List & View: List all sites, get detailed site information, count sites
• Health: Run health checks, track non-MainWP changes
• Sync: Force synchronization to get the latest site data
• Lifecycle: Add, reconnect, disconnect, suspend, unsuspend, remove sites
• Edit: Modify site settings and group assignments

Update Management (9 tools)

• Update Overview: See all pending updates across your entire network
• WordPress Core: Update WordPress to the latest version
• Plugins: Update individual or all plugins
• Themes: Update individual or all themes
• Translations: Update site translations
• Ignore Management: Ignore/unignore specific updates, list ignored updates
• Dry-Run Mode: Preview what updates would be applied without making changes

Plugin Management (5 tools)

• Inventory: List all plugins installed on any site
• Activation: Activate or deactivate plugins
• Installation: Install plugins from WordPress.org
• Removal: Delete unused plugins

Theme Management (4 tools)

• Inventory: List all themes installed on any site
• Activation: Change the active theme on any site
• Installation: Install themes from WordPress.org
• Removal: Delete unused themes

Client Management (5 tools) - Pro

• CRM: List, add, edit, delete clients
• Site Assignment: Assign sites to clients

Cost Tracking (5 tools) - Pro

• Expenses: Track plugin, theme, hosting, domain, and service costs
• Renewals: Monitor recurring costs and renewal dates

Tag Management (2 tools)

• Organization: List all tags, get sites by tag

Safety & Security

• Dry-Run by Default: All destructive operations simulate first
• Bulk Confirmation: Multi-site operations require explicit confirmation
• Rate Limiting: Prevents overwhelming your servers
• Pro Feature Handling: Clear error messages when Pro extensions are required

---

Architecture

┌─────────────────┐     stdio      ┌─────────────────┐
│   Claude Code   │◄──────────────►│  MainWP MCP     │
│   (AI Client)   │                │    Server       │
└─────────────────┘                └────────┬────────┘
                                            │
                                            │ HTTPS REST API
                                            ▼
                                   ┌─────────────────┐
                                   │ MainWP Dashboard│
                                   │   (WordPress)   │
                                   └────────┬────────┘
                                            │
                              ┌─────────────┼─────────────┐
                              │             │             │
                              ▼             ▼             ▼
                        ┌──────────┐ ┌──────────┐ ┌──────────┐
                        │  Site 1  │ │  Site 2  │ │  Site N  │
                        │(WP+Child)│ │(WP+Child)│ │(WP+Child)│
                        └──────────┘ └──────────┘ └──────────┘

---

Prerequisites

Required Software

| Software | Version | Purpose | |----------|---------|---------| | Node.js | 18.0.0+ | Runtime environment | | npm | 8.0.0+ | Package management | | Git | Any | Cloning the repository |

Required Infrastructure

1. MainWP Dashboard - A WordPress installation with the MainWP Dashboard plugin installed and activated

1. MainWP Child Sites - Each WordPress site you want to manage must have the MainWP Child plugin installed and connected to your Dashboard

1. REST API Access - MainWP Dashboard must have the REST API enabled (included in MainWP 4.0+)

Recommended

• HTTPS: Your MainWP Dashboard should be served over HTTPS
• PHP 8.1+: On your MainWP Dashboard for best performance
• Adequate Memory: 512MB+ PHP memory limit on Dashboard (1GB for 50+ sites)

---

Installation

Step 1: Clone the Repository

git clone https://github.com/yourusername/mainwp-mcp.git
cd mainwp-mcp

Step 2: Install Dependencies

npm install

This installs:

• @modelcontextprotocol/sdk - MCP protocol implementation
• axios - HTTP client for API requests
• zod - Runtime type validation
• dotenv - Environment variable management

Step 3: Build the Project

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Step 4: Verify Installation

npm start

You should see:

mainwp-mcp v1.0.0 started

Press Ctrl+C to stop the server.

---

MainWP Dashboard Setup

Before using this MCP server, you need to configure your MainWP Dashboard.

Step 1: Install MainWP Dashboard

If you haven't already:

1. Log into your WordPress admin panel
2. Go to Plugins → Add New
3. Search for "MainWP Dashboard"
4. Click Install Now, then Activate
5. Complete the MainWP setup wizard

Step 2: Connect Child Sites

For each WordPress site you want to manage:

1. On the child site, install and activate the MainWP Child plugin
2. In your MainWP Dashboard, go to MainWP → Sites → Add New
3. Enter the site URL and administrator credentials
4. Click Add Site

Step 3: Enable REST API

1. In your MainWP Dashboard, go to MainWP → Settings → REST API
2. Ensure the REST API is Enabled
3. Click Add API Key
4. Fill in the details:

• Description: Claude Code MCP Server (or any descriptive name)
• Permissions: Select the permissions you want to grant
• Read: Sites, plugins, themes, updates (recommended)
• Write: Updates, plugin activation (optional)

1. Click Generate API Key
2. Important: Copy both the Consumer Key and Consumer Secret immediately - the secret won't be shown again

Step 4: Note Your API Credentials

You'll need:

• Dashboard URL: e.g., https://your-mainwp-dashboard.com
• Consumer Key: A 40-character hex string
• Consumer Secret: A 40-character hex string

The API key format used by this server is: consumer_key==consumer_secret

---

Configuration

Environment Variables

Create a .env.local file in the project root:

cp .env.example .env.local

Edit .env.local with your settings:

# Required: MainWP Dashboard URL
# The full URL to your MainWP Dashboard WordPress installation
MAINWP_DASHBOARD_URL=https://your-mainwp-dashboard.com

# Required: API Key
# Format: consumer_key==consumer_secret (note the double equals sign)
MAINWP_API_KEY=abc123def456...==xyz789...

# Optional: Safety Settings
# Enable dry-run mode by default (recommended: true)
MAINWP_ENABLE_DRY_RUN_BY_DEFAULT=true

# Require explicit confirmation for bulk operations (recommended: true)
MAINWP_REQUIRE_CONFIRMATION_BULK=true

# Optional: Test mode (no side effects)
MAINWP_TEST_MODE=false

# Rate limit: maximum API requests per minute (default: 60)
MAINWP_RATE_LIMIT_PER_MINUTE=60

Configuration Options Reference

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MAINWP_DASHBOARD_URL | Yes | - | Full URL to your MainWP Dashboard | | MAINWP_API_KEY | Yes | - | API credentials in key==secret format | | MAINWP_ENABLE_DRY_RUN_BY_DEFAULT | No | true | Simulate operations by default | | MAINWP_REQUIRE_CONFIRMATION_BULK | No | true | Require confirmation for multi-site ops | | MAINWP_TEST_MODE | No | false | Simulate mutating operations without side effects | | MAINWP_RATE_LIMIT_PER_MINUTE | No | 60 | Max API requests per minute |

---

Claude Code Integration

Option 1: Global Configuration (Recommended)

Add to your Claude Code MCP configuration file:

Linux/macOS: ~/.config/claude-code/mcp.json Windows: %APPDATA%\claude-code\mcp.json

{
  "mcpServers": {
    "mainwp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mainwp-mcp/dist/index.js"],
      "env": {
        "MAINWP_DASHBOARD_URL": "https://your-mainwp-dashboard.com",
        "MAINWP_API_KEY": "your_consumer_key==your_consumer_secret",
        "MAINWP_ENABLE_DRY_RUN_BY_DEFAULT": "true",
        "MAINWP_REQUIRE_CONFIRMATION_BULK": "true",
        "MAINWP_TEST_MODE": "false",
        "MAINWP_RATE_LIMIT_PER_MINUTE": "60"
      }
    }
  }
}

Option 2: Project-Specific Configuration

Create .mcp.json in your project directory:

{
  "mcpServers": {
    "mainwp": {
      "type": "stdio",
      "command": "node",
      "args": ["./node_modules/mainwp-mcp/dist/index.js"],
      "env": {
        "MAINWP_DASHBOARD_URL": "https://your-mainwp-dashboard.com",
        "MAINWP_API_KEY": "your_consumer_key==your_consumer_secret"
      }
    }
  }
}

Verifying the Integration

1. Restart Claude Code after adding the configuration
2. Ask Claude: "What MCP tools are available?"
3. You should see the mainwp_* tools listed
4. Test with: "List all MainWP sites"

---

Available Tools

Site Management Tools

mainwp_sites_list

List all connected WordPress sites.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | status | string | No | Filter by status: connected, disconnected, all |

Example Response:

{
  "sites": [
    {
      "id": "1",
      "name": "My Blog",
      "url": "https://myblog.com",
      "status": "connected",
      "wp_version": "6.4.2",
      "php_version": "8.2",
      "last_sync": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

mainwp_sites_get

Get detailed information for a specific site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID from MainWP |

Returns: Comprehensive site data including plugins, themes, health score, database size, etc.

mainwp_sites_count

Get the total count of connected sites.

Parameters: None

mainwp_sites_sync

Force synchronization of site data.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID to sync |

mainwp_sites_check

Run a health check on a site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID to check |

mainwp_sites_add

Add a new site to MainWP Dashboard.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | url | string | Yes | The site URL | | admin_username | string | Yes | WordPress admin username | | name | string | No | Display name for the site |

mainwp_sites_reconnect

Reconnect a disconnected site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID to reconnect |

mainwp_sites_disconnect

Disconnect a site from MainWP (does not delete the site).

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID to disconnect |

---

Update Management Tools

mainwp_updates_list

List all pending updates across all sites.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | No | Filter to specific site | | type | string | No | Filter by type: wp, plugins, themes, all |

Example Response:

{
  "updates": [
    {
      "site_id": "1",
      "site_name": "My Blog",
      "site_url": "https://myblog.com",
      "wp_upgrades": {
        "current": "6.4.1",
        "new": "6.4.2"
      },
      "plugin_upgrades": {
        "akismet": {
          "name": "Akismet",
          "version": "5.0",
          "new_version": "5.1"
        }
      }
    }
  ]
}

mainwp_updates_apply

Apply all pending updates for a site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID to update | | dry_run | boolean | No | Simulate without applying (default: true) |

mainwp_updates_wp

Update WordPress core on a site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID | | dry_run | boolean | No | Simulate without applying (default: true) |

mainwp_updates_plugins

Update plugins on a site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID | | plugins | string[] | No | Specific plugin slugs (omit for all) | | dry_run | boolean | No | Simulate without applying (default: true) |

mainwp_updates_themes

Update themes on a site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID | | themes | string[] | No | Specific theme slugs (omit for all) | | dry_run | boolean | No | Simulate without applying (default: true) |

---

Plugin Management Tools

mainwp_plugins_list

List all plugins installed on a site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID | | status | string | No | Filter: active, inactive, all |

Example Response:

{
  "plugins": [
    {
      "name": "Akismet Anti-spam",
      "slug": "akismet",
      "version": "5.1",
      "active": true,
      "update": null
    },
    {
      "name": "Hello Dolly",
      "slug": "hello-dolly",
      "version": "1.7.2",
      "active": false,
      "update": null
    }
  ]
}

mainwp_plugins_activate

Activate a plugin on a site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID | | plugin | string | Yes | Plugin slug to activate |

mainwp_plugins_deactivate

Deactivate a plugin on a site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | string | Yes | The site ID | | plugin | string | Yes | Plugin slug to deactivate |

---

Theme Management Tools

mainwp_themes_list

List all themes installed on a site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | site_id | str

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cvsloane
• Source: cvsloane/mainwp-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.