Skip to main content
Glama

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

Demo

License: GPL v2+ Node 18+ Self-hosted

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: WordPress MCP Server

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.

Available Tools

23 tools
cron_listcron_listB
Read-onlyIdempotent

All scheduled WP-Cron events, soonest first.

Inputs: no named parameters.

db_querydb_queryA
Read-onlyIdempotent

Run a read-only SQL query (SELECT / SHOW / DESCRIBE / EXPLAIN, one statement). Use LIMIT.

Inputs: sql (required).

diagnosticsdiagnosticsB
Read-onlyIdempotent

PHP/memory config, autoload options size, DB size and largest tables, transients/revisions counts, active caching plugins.

Inputs: no named parameters.

elementor_data_getelementor_data_getB
Read-onlyIdempotent

Raw _elementor_data JSON of a page. Can be very large.

Inputs: post_id (required).

file_listfile_listB
Read-onlyIdempotent

List a directory inside wp-content.

Inputs: path.

file_readfile_readB
Read-onlyIdempotent

Read a file inside wp-content.

Inputs: path (required).

health_check_runhealth_check_runA
Read-onlyIdempotent

Run the health check now (DB connection, PHP fatals in debug.log, low disk space, bridge disabled).

Inputs: no named parameters.

health_check_statushealth_check_statusA
Read-onlyIdempotent

Result of the last hourly self-check (if health checks are enabled).

Inputs: no named parameters.

media_listmedia_listC
Read-onlyIdempotent

List media library items.

Inputs: limit.

option_getoption_getB
Read-onlyIdempotent

Read a WordPress option by name.

Inputs: name (required).

order_getorder_getB
Read-onlyIdempotent

Full order detail including line items and addresses.

Inputs: id (required).

order_listorder_listB
Read-onlyIdempotent

List WooCommerce orders (WooCommerce must be active).

Inputs: limit, search, status.

plugin_listplugin_listA
Read-onlyIdempotent

List installed plugins and their active state.

Inputs: no named parameters.

post_getpost_getB
Read-onlyIdempotent

Get one post by ID.

Inputs: id (required).

post_listpost_listC
Read-onlyIdempotent

List posts/pages/custom post types.

Inputs: limit, search, post_type, post_status.

search_replace_previewsearch_replace_previewA
Read-onlyIdempotent

DRY RUN of a serialization-safe search/replace across the database. Shows what would change, changes nothing.

Inputs: search (required), replace (required), tables.

site_infosite_infoA
Read-onlyIdempotent

Site name, label, URL, WordPress / theme / WooCommerce versions. Good first call.

Inputs: no named parameters.

template_exporttemplate_exportA
Read-onlyIdempotent

Export a page's Elementor data + settings so it can be copied to another site with template_import.

Inputs: post_id (required).

term_listterm_listC
Read-onlyIdempotent

List taxonomy terms.

Inputs: taxonomy.

theme_listtheme_listA
Read-onlyIdempotent

List installed themes.

Inputs: no named parameters.

wpssh_pingPing siteA
Read-only

Check that the WP SSH plugin is installed and reachable (no key needed). Returns plugin, version, site, label.

Inputs: no named parameters.

wpssh_sitesList configured sitesA
Read-only

List the WordPress sites this server can reach and the current safety mode ("read"). Never shows keys.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools target clearly distinct resources and actions, such as order_list vs order_get and file_list vs file_read. There is mild overlap among site-introspection tools (wpssh_sites, wpssh_ping, site_info), but descriptions make their purposes distinguishable.

    Naming Consistency3/5

    Many tools follow a resource_verb pattern (order_list, post_get, option_get), but the set also includes bare nouns (diagnostics), prefixed tools (wpssh_sites, wpssh_ping), and mixed orderings (health_check_run, search_replace_preview). It remains readable but is not a single predictable convention.

    Tool Count3/5

    At 23 tools the surface is heavy for a WordPress admin server, though the breadth of resources justifies some of it. Several list/get pairs could be consolidated or grouped, making it borderline rather than well-scoped.

    Completeness4/5

    The read-only surface covers posts, terms, menus, media, plugins, themes, options, cron, orders, files, Elementor data, diagnostics, and raw DB reads. Some common read operations are missing (users, comments, WooCommerce products beyond orders), but db_query provides a workaround and the absence of writes is consistent with the stated read safety mode.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers