# Mainwp Mcp

> MCP server from cvsloane/mainwp-mcp.

- **Type:** MCP server
- **Install:** `agentstack add mcp-cvsloane-mainwp-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cvsloane](https://agentstack.voostack.com/s/cvsloane)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cvsloane](https://github.com/cvsloane)
- **Source:** https://github.com/cvsloane/mainwp-mcp

## Install

```sh
agentstack add mcp-cvsloane-mainwp-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MainWP MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to manage WordPress sites through the [MainWP Dashboard](https://mainwp.com/) 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](https://wordpress.org/plugins/mainwp/) installed and activated

2. **MainWP Child Sites** - Each WordPress site you want to manage must have the [MainWP Child plugin](https://wordpress.org/plugins/mainwp-child/) installed and connected to your Dashboard

3. **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

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

### Step 2: Install Dependencies

```bash
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

```bash
npm run build
```

This compiles TypeScript to JavaScript in the `dist/` directory.

### Step 4: Verify Installation

```bash
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)
5. Click **Generate API Key**
6. **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:

```bash
cp .env.example .env.local
```

Edit `.env.local` with your settings:

```bash
# 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`

```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:

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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](https://github.com/cvsloane)
- **Source:** [cvsloane/mainwp-mcp](https://github.com/cvsloane/mainwp-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cvsloane-mainwp-mcp
- Seller: https://agentstack.voostack.com/s/cvsloane
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.