Cowboy MCP Server

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, Cursor, Claude Code, Codex, Gemini and any other MCP client can manage the site in plain English — with per-change undo, database checkpoints and an audit log, so it can be trusted on a live site.

Install: WordPress.org plugin directory (one click, auto-updates) · Try it in your browser: Live Preview · Website & guides: cowboymcp.com · Questions: support forum · Bugs: issues

---

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.
• Two ways to connect. A Bearer-token endpoint for terminal agents and editors, and a one-click OAuth 2.1 connector (admin consent, scope choice) for the Claude desktop/web apps and ChatGPT.
• 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

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.

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) — turn on Settings → Cowboy MCP → Settings → Desktop Connector, add the endpoint as a custom connector in the app (for Claude, the Add to Claude button on the Connections tab fills it in for you), 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"

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).