wp-ssh MCP server

wp-ssh-mcp: WordPress MCP server for the WP SSH plugin

Let Claude, Cursor, Claude Code and other MCP clients manage your self-hosted WordPress site (posts, WooCommerce, Elementor, diagnostics, files) without SSH access.

wp-ssh-mcp is a small program that runs on your own computer. It turns the WP SSH plugin's HTTPS endpoint into MCP tools, so your AI sees post_list, order_get, elementor_data_set and so on, with proper parameter schemas. No hosted relay, no accounts: your key stays on your machine.

This needs two pieces. The WordPress plugin does the real work on your site; wp-ssh-mcp only connects your AI app to it.

Claude Desktop / Cursor / Claude Code
        │   MCP (local, stdio)
        ▼
   wp-ssh-mcp                 ← this repo, runs on your computer
        │   HTTPS + X-WPSSH-Key
        ▼
   your WordPress site        ← WP SSH plugin (separate repo)

Quick start

Step 1: install the plugin on your WordPress site (once per site)

1. Get it from MSSOFTPC/wp-ssh (Releases → wp-ssh.zip).
2. WordPress admin: Plugins → Add New → Upload Plugin → Activate.
3. Tools → WP SSH: tick Enable bridge, copy the Secret key.

Step 2: connect your AI app (see Install for Claude Desktop, Claude Code and Cursor)

claude mcp add my-site -e WPSSH_URL=https://yoursite.com -e WPSSH_KEY=your-key -- npx -y wp-ssh-mcp

Then ask: "Run diagnostics on my site."

Safe by default

The server starts in read mode. Write tools are not even shown to the AI until you opt in.

WPSSH_MODE	What the AI can do	Action tools
read (default)	Look, never touch: site info, diagnostics, posts, orders, options, file reads, SELECT queries, dry-run search-replace, Elementor export	21
write	+ content changes: create/update posts, order status, Elementor data/import, product attributes, cache clear, media upload, menus	34
full	+ risky: file writes/restore, write SQL, permanent delete, real search-replace, plugin activate/deactivate	41

More safety built in:

• Risky tools are marked destructive, so MCP clients show an approval prompt.
• db_query accepts one read-only statement only. Writes need the separate db_query_write tool (full mode).
• search_replace_preview always sends dry_run: true; the model cannot override it.
• confirm: true is never added automatically. The model must pass it, and tool descriptions tell it to do so only after your approval.
• The plugin's own protections still apply (Read-only mode, IP allowlist, lockout, auto-backups, activity log).
• Refuses plain http:// (except localhost), refuses to follow redirects (the key is never forwarded), and never prints your key.

Install

Requires Node.js 18+ and the WP SSH plugin active on your site (Tools → WP SSH → copy the secret key, tick Enable bridge).

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "my-site": {
      "command": "npx",
      "args": ["-y", "wp-ssh-mcp"],
      "env": {
        "WPSSH_URL": "https://yoursite.com",
        "WPSSH_KEY": "your-64-char-secret-key",
        "WPSSH_MODE": "read"
      }
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add my-site -e WPSSH_URL=https://yoursite.com -e WPSSH_KEY=your-key -- npx -y wp-ssh-mcp

Cursor

~/.cursor/mcp.json (or project .cursor/mcp.json): same mcpServers block as above.

Several sites

"env": {
  "WPSSH_SITES": "[{\"name\":\"shop\",\"url\":\"https://shop.com\",\"key\":\"...\"},{\"name\":\"blog\",\"url\":\"https://blog.com\",\"key\":\"...\"}]",
  "WPSSH_MODE": "read"
}

Every tool then gets a required site parameter (shop or blog).

Run from source

git clone https://github.com/MSSOFTPC/wp-ssh-mcp
cd wp-ssh-mcp
npm install && npm run build
# then use  "command": "node", "args": ["/full/path/to/wp-ssh-mcp/dist/index.js"]

Configuration

Variable	Meaning
WPSSH_URL, WPSSH_KEY	One site. URL like https://example.com, key from Tools → WP SSH
WPSSH_NAME	Optional name for the single site (default default)
WPSSH_SITES	JSON array for several sites (see above)
WPSSH_MODE	read (default), write, full
WPSSH_ALLOW_HTTP	1 to allow http:// on a trusted private network
WPSSH_TIMEOUT_MS	Request timeout, default 30000
WPSSH_MAX_CHARS	Max characters returned per call (default 60000). Big Elementor pages are truncated with a hint

Example prompts

• "Run diagnostics on my site and tell me what is slowing it down."
• "List draft posts tagged ready and show me before publishing any."
• "Preview a search-replace from http://old.com to https://new.com. Don't apply it."
• "Export the Elementor design of page 120 from shop and import it as a draft on blog."
• "Show today's WooCommerce orders and summarise by status."

ChatGPT, n8n, Make, Zapier (no MCP needed)

This repo also ships OpenAPI 3.1 files generated from the same action list:

• openapi.json: read + content-write actions (use this one)
• openapi.full.json: everything, including risky actions (only for agents you fully trust)

Custom GPT: Configure → Actions → Import the file → set the server URL to your site → Authentication: API Key, Custom, header name X-WPSSH-Key. Note that ChatGPT calls your site from OpenAI's servers, so an IP allowlist is not practical there; keep the plugin in Read-only mode unless you are actively making changes.

Regenerate after changing src/spec.ts: npm run build && npm run gen:openapi.

Privacy

wp-ssh-mcp talks only to the site URLs you configure. No telemetry, no analytics, no third-party servers. What the AI sees is the output of the tools you allow, and it is handled under your AI provider's terms.

Troubleshooting

Symptom	Fix
"wrong or missing secret key"	Re-copy the key from Tools → WP SSH (regenerating invalidates the old one)
403	Bridge disabled, Read-only mode on in the plugin, or your IP is not on the allowlist
404	Plugin inactive, or permalinks/REST API blocked by a security plugin or server rule
"redirect" error	Use the exact final URL (https vs http, www vs non-www)
Tools missing	You are in read mode; set WPSSH_MODE=write or full and restart the client
Nothing shows in Claude Desktop	Check JSON syntax, fully restart the app, run npx wp-ssh-mcp --help in a terminal

Development

npm install
npm test            # builds and runs the end-to-end smoke test against a mock endpoint
npm run gen:openapi

src/spec.ts is the single list of actions. Add an action there and both the MCP tool and the OpenAPI schema appear.

License

GPL-2.0-or-later, same as the plugin.