Cowboy MCP

Cowboy MCP 🤠 — Free WordPress MCP Server with Undo

Cowboy MCP is a free, open-source WordPress plugin that turns any WordPress site into a Model Context Protocol (MCP) server over Streamable HTTP, so Claude, ChatGPT, Gemini, Grok, Perplexity, Muse, Cursor, VS Code, Claude Code, Codex, n8n, OpenClaw, Hermes Agent and any other MCP client can manage the site in plain English through 203 tools — with per-change undo, database checkpoints and an audit log, so it can be trusted on a live site.

Install: WordPress.org plugin directory
Website & guides: cowboymcp.com

▶ Watch the 90-second demo

---

Why Cowboy MCP?

• Every tool is free. Up to 203 built-in tools plus every ability your plugins register through the WordPress Abilities API — content, Gutenberg/Site Editor, WooCommerce, users, media, menus, plugins, themes, files, database, WP-CLI, diagnostics, revisions, SEO (Yoast, Rank Math, AIOSEO, SEOPress), The Events Calendar, ACF, Elementor, Beaver Builder, SiteOrigin, Wordfence, caching, forms — GPL-licensed, no Pro tier, no credits, no usage meter.
• Every change is undoable. A per-change undo journal (before-state snapshots, conflict detection, batch undo) plus one-click database checkpoints, with an always-on audit log. Plugin and theme updates take a file backup and a checkpoint first and auto-restore if the post-update health check fails.
• Nothing in the middle. The MCP endpoint runs inside your WordPress install. No hosted relay, no account, no telemetry — your AI client connects straight to your site.
• Safe by default. Safe mode (confirmation for destructive tools), dry run on every write tool, per-credential read-only/custom scoping, hashed keys shown once, per-key rate limits, denylists for sensitive options / dangerous SQL / WP-CLI commands, SSRF protection, path confinement to wp-content, and a Power mode only a human can enable in wp-admin.
• One-click sign-in for every app. Every app sends you to a sign-in page on your own site: Claude, ChatGPT, Gemini, Grok, Perplexity, Cursor and VS Code with one button or a pasted link, Claude Code, Codex, Gemini CLI and Muse Code with one command, Muse, OpenClaw and Hermes Agent from one pasted message, n8n through OAuth2. The consent screen names the app and lets you grant full access, read-only or a hand-picked list of tools; nothing is granted until you click Approve. API keys remain for scripts, CI and editors without browser sign-in (Windsurf, Cline, Zed).
• Works locally too. Local, Studio, MAMP, DevKinsta, wp-env: terminal tools connect with a key as on a live site; Claude Desktop connects through an mcp-remote bridge the Connections tab generates for you.
• Context-efficient. tools/list returns two gateway tools (cowboy_discover, cowboy_run); the agent discovers and runs the other tools on demand instead of loading 203 schemas into its context. On WordPress 6.9+ every tool is also a cowboy-mcp/* ability for WP-CLI, REST and the official MCP Adapter — with undo.
• Zero dependencies. Native WordPress APIs only — no Composer, no npm, no build step, no wp-admin/includes at request time. Works on hosts without WP-CLI or shell_exec().

"More access than any other MCP offers, easy to use, LOVE the change journal and the checkpoints — safe if you break something." — WordPress.org review

Tool coverage

Area	Tools	What the agent can do
Content	5 posts/pages/CPTs · 4 taxonomies · 4 comments · 4 media · 6 menus · 1 options	draft, edit, schedule, publish; upload media, fix alt text; build nav menus
Gutenberg & Site Editor	15 (8 on classic themes)	read a page as a block tree and edit it by path; block types, patterns, FSE templates/parts, global styles, navigations
Site administration	5 users · 6 plugins · 5 themes · 4 files · 5 database · 3 WP-CLI/system · 1 site health	install/update/delete plugins & themes safely, manage roles, edit files in wp-content, repair tables, run WP-CLI
Diagnostics	10	error log, HTTP & email tests, hooks, transients, REST routes, thumbnails, rewrite rules, snapshot, Connection Doctor
Safety	6 rollback · 2 batch/audit	list & undo changes, create/list/restore/delete checkpoints, batch execution, audit-log retrieval
WooCommerce	40	products & variations, orders & refunds, customers, coupons, tax/shipping/payment settings, reports
Wordfence	17	scans, blocks, firewall, live traffic, activity, settings
ACF / Elementor	9 / 7	field groups, fields, repeaters / templates, page content, global styles, widgets
Beaver Builder / SiteOrigin	7 / 12	builder pages, layouts with dry-run diff, modules, global settings / layouts and row/widget edits, prebuilt layouts, widgets, settings, Widgets Bundle activation
Revisions / Events	3 / 13	list, diff & restore post revisions / The Events Calendar events, venues, organizers + Events Calendar Pro recurrence
SEO / Cache / Forms	4 / 4 / 1	Yoast, Rank Math, All in One SEO & SEOPress meta read/write/audit / WP Rocket, LiteSpeed, W3TC / WPForms, Gravity Forms, CF7

Most other page builders are supported too: a builder that keeps its layout in post content or post meta is edited through the standard post tools, with the same dry run and per-change undo.

Plus 17 read-only resources (incl. wordpress://tools/catalog), 4 resource templates (wordpress://posts/{id}, wordpress://options/{name}, wordpress://plugins/{slug}, wordpress://users/{id}) and 8 workflow prompts with argument auto-completion. Integrations register only when their plugin is active.

Requirements

• WordPress 6.2+ (tested up to 7.1)
• PHP 8.0+
• HTTPS for the OAuth connector and for cloud clients (claude.ai, ChatGPT); plain HTTP is fine for terminal tools on a local site

Installation

1. Plugins → Add New, search for Cowboy MCP, install and activate — or download from WordPress.org.
2. Settings → Cowboy MCP → Generate API Key. Copy it — it is shown once and stored hashed.
3. Connect your client (below). The Connection tab shows every snippet pre-filled with your site's endpoint.

Updates arrive through the normal WordPress updates screen.

Connect your app

Every app signs in through a consent screen on your own site; no API key to paste. The full matrix — plan gates, whether a local site works, and the date each row was last verified end to end — is at cowboymcp.com/connect.

App	Plan needed	Button or command	Guide
Claude (claude.ai)	Any Claude plan; Free allows one custom connector. Team and Enterprise: an owner adds it first	Connections tab → Add to Claude	connect-wordpress-to-claude
Claude Desktop	Same as claude.ai	Connections tab → Add to Claude, or Customize → Connectors → Add custom connector	connect-wordpress-to-claude-desktop
Claude Code	A Claude plan that includes Claude Code (Pro or Max), or API billing	Connections tab → Claude Code panel → run two lines (claude mcp add, claude mcp login)	connect-wordpress-to-claude-code
ChatGPT	Business, Enterprise or Edu workspace, on the web; Pro connects one server read-only. No Developer mode	Connections tab → Open ChatGPT, then Plugins → Add → Add custom MCP server → Create as a plugin	connect-wordpress-to-chatgpt
Codex CLI and app	A ChatGPT plan that includes Codex (Plus, Pro, Business, Enterprise or Edu), or an API key	Connections tab → Codex panel → one codex mcp add command	connect-wordpress-to-codex
Perplexity	Pro, Max or Enterprise. Free has no custom connectors	Connections tab → Open Perplexity, then Plugins (or Customize → Connectors) → Add custom → Add MCP connector	connect-wordpress-to-perplexity
Grok	Any, including the free plan	Connections tab → Open Grok, then grok.com/connectors → New Connector → Custom	connect-wordpress-to-grok
Gemini app	A personal Google account in the US, 18+, Gemini in English; no paid plan listed	Connections tab → Open Gemini, then Customize → Connectors → + Custom	connect-wordpress-to-gemini
Gemini CLI	A Google account; the free tier works	Connections tab → Gemini CLI panel → one gemini mcp add command, then /mcp auth	connect-wordpress-to-gemini
Muse (Meta)	Free; Meta offers Muse in the United States and Canada	Connections tab → Muse panel → Copy message, paste it into a new Muse chat	connect-wordpress-to-muse
Muse Code	Same Muse account	Connections tab → Muse Code panel → Copy message, paste into muse, then one muse mcp login command	connect-wordpress-to-muse#muse-code
Cursor	Any Cursor plan	Connections tab → Add to Cursor	connect-wordpress-to-cursor
VS Code (GitHub Copilot)	Any Copilot plan, including Free	Connections tab → Install in VS Code	connect-wordpress-to-vs-code
n8n	Any n8n Cloud plan, or self-hosted n8n (Community Edition included)	Connections tab → n8n panel; add an MCP Client Tool node with an MCP OAuth2 credential	connect-wordpress-to-n8n
OpenClaw	A running OpenClaw gateway	Connections tab → OpenClaw panel → Copy message, paste into your OpenClaw chat; or openclaw mcp add + openclaw mcp login	connect-wordpress-to-openclaw
Hermes Agent	Hermes Agent by Nous Research; the chat path needs its connection tool, the terminal command works on every install	Connections tab → Hermes Agent panel → Copy message, paste into your Hermes chat; or one hermes mcp add … --auth oauth	connect-wordpress-to-hermes-agent

Windsurf, Cline, Zed, LibreChat and any other Streamable HTTP client connect with a scoped API key (config blocks below); Opencode signs in with the same browser flow.

Connecting an agent

The endpoint is https://yoursite.com/wp-json/cowboy-mcp/v1/endpoint (JSON-RPC 2.0 over Streamable HTTP, MCP 2025-06-18).

Claude Code

claude mcp add --transport http your-site https://yoursite.com/wp-json/cowboy-mcp/v1/endpoint \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude desktop & web, ChatGPT (one-click, no key) — click Add to Claude / Open ChatGPT on the Connections tab (browser sign-in is switched on for you; for ChatGPT paste the copied link as a custom MCP server), approve the consent screen on your site (choose full, read-only or custom access). Requires a public HTTPS site.

Claude Desktop on a local site — use the mcp-remote bridge config shown on the Connections tab:

{
  "mcpServers": {
    "your-site": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://yoursite.local/wp-json/cowboy-mcp/v1/endpoint",
        "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer YOUR_API_KEY" }
    }
  }
}

Cursor / Windsurf (Devin Desktop) (~/.cursor/mcp.json, ~/.config/devin/mcp_config.json)

{
  "mcpServers": {
    "your-site": {
      "url": "https://yoursite.com/wp-json/cowboy-mcp/v1/endpoint",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Cline: add "type": "streamableHttp" to the entry. VS Code (.vscode/mcp.json): use servers instead of mcpServers and add "type": "http". Zed: put the same url + headers under context_servers in its settings.

Codex CLI — Codex reads the key each time it starts, so add the export to your shell profile too.

export COWBOY_MCP_API_KEY="YOUR_API_KEY"
codex mcp add your-site --url https://yoursite.com/wp-json/cowboy-mcp/v1/endpoint --bearer-token-env-var COWBOY_MCP_API_KEY

Gemini CLI

gemini mcp add --scope user --transport http your-site https://yoursite.com/wp-json/cowboy-mcp/v1/endpoint \
  --header "Authorization: Bearer YOUR_API_KEY"

Gemini app, Grok, Perplexity, Meta Muse, OpenClaw, Hermes Agent, n8n (no key) — each has its own panel on the Connections tab: the cloud apps take your connection link as a custom MCP server, Muse, OpenClaw and Hermes take a message you paste into their chat, and n8n's MCP Client Tool node uses MCP OAuth2. All of them sign in on your site through the browser.

Any client that speaks Streamable HTTP with a Bearer header works the same way (n8n, Opencode, LibreChat, your own agent). Opencode: set "oauth": false on the remote server so it uses the key. Step-by-step guides per client: cowboymcp.com.

Quick smoke test with curl

curl -s -X POST https://yoursite.com/wp-json/cowboy-mcp/v1/endpoint \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cowboy_run","arguments":{"tool":"wp_site_info","arguments":{}}}}'

Safety model

• Safe mode (default on): tools annotated destructiveHint refuse to run until the call is resent with confirm: true; the refusal includes a preview.
• Dry run: every non-read-only tool accepts dry_run: true and reports exactly what would change.
• Undo journal: before-state snapshots for journaled changes (posts, options, users, media, menus, terms, comments, WooCommerce objects, SEO meta, Gutenberg/FSE edits, search-replace rows, plugin/theme packages); wp_list_changes / wp_undo_change, batch undo, conflict detection, redo-on-undo; 7-day retention by default.
• Database checkpoints: prefix-scoped dump of the site's tables, atomic restore; up to 5 kept; taken automatically before plugin/theme updates and mutating WP-CLI commands. Checkpoints restore tables, not uploaded files or code.
• Audit log: every tool call, error and auth event in {prefix}cowboy_mcp_audit_log (key, tool, arguments, result, IP); pruned after 30 days; secrets redacted on read.
• Scoped credentials: API keys and OAuth connections carry {mode: full|read_only|custom, allowed_tools[]}; enforced at dispatch, also for tools called through cowboy_run and batches. readOnlyHint is treated as a security boundary.
• Keys & limits: keys stored as one-way hashes, shown once, revocable individually; per-key rate limit (120/min default); request Origin allowlist; OAuth tokens stored hashed, off by default, admin consent required.
• Guardrails: protected-option denylist (siteurl, active_plugins, credentials, the plugin's own settings…), dangerous-SQL and WP-CLI blocklists (eval, shell, db drop, …) applied on a shell-style tokenizer, SSRF validation on outbound requests, wp-content path confinement with atomic writes, a PHP syntax check before every file write and no mu-plugins writes without Power mode, self-delete and last-administrator protection.
• Power mode: an admin-only checkbox that lifts the curated guardrails for one-off jobs; it can never be enabled through the API, and it never lifts credential-option protection, secret redaction or self-protection.
• Connection Doctor: one-click self-test (HTTPS, reachability, REST, OAuth discovery, host blockers such as Cloudflare challenges, ModSecurity-style WAFs, LiteSpeed caching) with fingerprinted causes and fixes; also wp cowboy-mcp doctor and the wp_connection_doctor tool.

How it compares

Factual, dated comparisons live on the site: all WordPress MCP plugins compared · vs Novamira · vs AI Engine · vs WPVibe · vs InstaWP · vs the WordPress MCP Adapter · self-hosted vs hosted. Short version: the endpoint is self-hosted with no relay or metering, every tool is free, and undo + checkpoints + audit log ship together.

Architecture

cowboy-mcp.php                 # entry point, constants, activation/uninstall
includes/
  class-mcp-transport.php      # REST route, JSON-RPC dispatch, sessions (Streamable HTTP)
  class-mcp-auth.php           # API keys (hashed), Bearer validation, rate limits, Origin allowlist
  class-mcp-oauth.php          # OAuth 2.1 authorization server (discovery, DCR, consent, tokens)
  class-mcp-security.php       # denylists, SSRF, SQL/WP-CLI gates, scoping, secret scrubbing
  class-mcp-tools.php          # registry, gateway meta-tools, dispatch, lazy domain loading
  class-mcp-rollback.php       # undo journal   class-mcp-checkpoint.php  # DB checkpoints
  class-mcp-audit-log.php      # audit table    class-mcp-installer.php   # WP.org package installer
  class-mcp-doctor.php         # Connection Doctor   class-mcp-compat.php  # admin-free reimplementations
  class-mcp-resources.php / class-mcp-prompts.php / class-mcp-completion.php
  tools/{core,gutenberg,acf,woocommerce,seo,forms,cache,elementor,wordfence}/
admin/                         # settings page (Connection, Settings, Activity, Logs, About), assets
languages/                     # 12 bundled locales for the admin UI (ru, uk, zh_CN, ja, ko, es, fr, de, pt_BR, it, hi, id)

Tool descriptions and error messages returned to agents are intentionally English; the admin UI is translated.

Extensibility

• cowboy_mcp_tools filter — register your own tool definitions and handlers.
• cowboy_mcp_tool_allowed filter — block specific tools per request.
• cowboy_mcp_allowed_origins filter — extend the request Origin allowlist.

Development

npx wp-env start          # local WordPress at http://localhost:8890 with this checkout mounted as the plugin
CLI="$(docker container ls -q --filter 'name=^[0-9a-f]+-cli-1$')"
docker exec "$CLI" wp plugin check cowboy-mcp --format=csv   # Plugin Check (install it in wp-env first)
find . -name '*.php' -not -path './node_modules/*' -exec php -l {} +  # syntax check

No build step. Pull requests welcome — keep the WordPress.org review invariants (no wp-admin/includes requires, no path constants, prepared/validated $wpdb queries, escaped output).

Support, reviews, security

• Questions and connection problems: the WordPress.org support forum — paste your Connection Doctor report; topics are usually answered within a day.
• Bugs and feature requests: GitHub issues.
• Security issues: please report privately through this repository's Security tab (private vulnerability reporting) rather than a public issue.
• Reviews: if Cowboy MCP saves you time, a review on WordPress.org helps other site owners find it.

License

GPL-2.0-or-later. © Andrew Ivanov (februality).