# wpagent-mcp

An [MCP](https://modelcontextprotocol.io) server that lets Claude — or any MCP-compatible client — actually operate a WordPress site: plugins, content, themes, menus, media, users, WooCommerce, Elementor and WP-CLI.

It talks to your site through the free [WpAgent](https://wpagent.dev) bridge plugin over a REST API where every request is signed with HMAC-SHA256. No site credentials are involved, and no data passes through a third-party service: the connection is client → your WordPress, directly.

## Install

Nothing to install ahead of time — the config below fetches it on demand.

1. Install the **WpAgent** plugin on your WordPress site and activate it.
2. In the WordPress admin, open **WpAgent** and generate an API key. Choose the permissions you want the assistant to have; a read-only key is a sound way to start.
3. Add the server to your MCP client. For Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wpagent": {
      "command": "npx",
      "args": ["-y", "wpagent-mcp"],
      "env": {
        "WP_SITE_URL": "https://your-site.com",
        "WP_API_KEY_ID": "wpaia_xxxxxxxxxxxx",
        "WP_API_SECRET": "the secret shown once when you generated the key"
      }
    }
  }
}
```

For Claude Code:

```bash
claude mcp add wpagent \
  --env WP_SITE_URL=https://your-site.com \
  --env WP_API_KEY_ID=wpaia_xxxxxxxxxxxx \
  --env WP_API_SECRET=... \
  -- npx -y wpagent-mcp
```

### Environment variables

| Variable | Required | What it is |
| --- | --- | --- |
| `WP_SITE_URL` | yes | Your site's base URL, no trailing slash |
| `WP_API_KEY_ID` | yes | The key id shown in the plugin |
| `WP_API_SECRET` | yes | The secret, displayed once at generation |
| `WP_SITE_LABEL` | no | A friendly name; defaults to the hostname |

## What it can do

| Area | Examples |
| --- | --- |
| Plugins | list, search wordpress.org, install, activate, deactivate, update, delete |
| Content | posts, pages, products, any custom post type, with meta and featured images |
| Themes | list, search, install, activate, theme mods, custom CSS, logo, colours |
| WooCommerce | settings, orders, coupons, shipping zones, payment gateways, tax rates, stats |
| Structure | menus, widgets, sidebars, taxonomies, terms, redirections |
| Media | browse, upload, delete |
| Users & comments | list, create, update, moderate |
| Audit | best-practices check over security, SEO, performance, with auto-fixes |
| WP-CLI | allowlisted commands, off unless enabled in `wp-config.php` |

## What it will not do

The API has no path to arbitrary PHP, no path to your database, and no path to `wp-config.php`. WP-CLI execution is disabled unless the site owner adds `define('WPAIA_ENABLE_WPCLI', true);` on the server, and even then only allowlisted commands run — `db`, `eval`, `eval-file`, `shell`, `server`, `config` and `package` are always refused.

## Safety

- Every request is signed with HMAC-SHA256 and carries a timestamp; requests older than five minutes are rejected.
- Permissions are per key and checked on every route, so a read-only key stays read-only.
- Every call is written to an audit log you can read in the WordPress admin.
- Revoking a key in WordPress takes effect immediately.

Ask the assistant to confirm before destructive actions, and keep a current backup — it can delete content when you tell it to.

## Related

- [WpAgent](https://wpagent.dev) — hosted dashboard built on the same bridge, with a free read-only tier
- The bridge plugin is GPL-2.0-or-later; this server is MIT.

## Licence

MIT © KipDev