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

Related MCP server: MCP Site Manager

Safe by default

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

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

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

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.