Cowboy MCP README

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) — 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"

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