Respira for WordPress

What this repo is, what it isn't

This repository is the public listing for the Respira WordPress MCP server. The server source ships on npm as @respira/wordpress-mcp-server. That wrapper code is MIT-licensed and you are welcome to read, fork, or vendor it.

The server is a client for the Respira WordPress plugin, not a standalone product. To do real work it needs:

• The Respira for WordPress plugin installed on your site

• A valid Respira API key bound to a license

The plugin is not open source. It is distributed under a commercial license. Free trial at respira.press, no card required. Paid plans start at 9 EUR a month.

In short: the wrapper you npx -y is open. The product behind it is not, and that is deliberate. If you want a self-contained "AI edits WordPress" stack with no commercial dependency, this is not it. The plugin is built and maintained full time by one person, and the license fees are how that happens.

For security reports see SECURITY.md.

Related MCP server: elementor-mcp-agent

What makes Respira different

Most WordPress MCP servers wrap the REST API. They can create posts and pages, but they cannot touch page builder content, which is where the actual site lives.

Respira ships a WordPress plugin that gives an AI agent native access to the builder's own data structures, plus the safety rails that make writing to a live site survivable.

Quick start

1. Install the WordPress plugin

Download from respira.press/plugin, upload to WordPress, activate, then go to Respira > API Keys and generate a key.

2. Connect your AI tool

The fastest path is the generated command at respira.press/dashboard/mcp, which fills in your site and key for you. Manual configs below.

claude mcp add respira-wordpress -- npx -y @respira/wordpress-mcp-server

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "respira-wordpress": {
      "command": "npx",
      "args": ["-y", "@respira/wordpress-mcp-server"]
    }
  }
}

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "respira-wordpress": {
      "command": "npx",
      "args": ["-y", "@respira/wordpress-mcp-server"]
    }
  }
}

Same shape as above. Codex uses TOML in ~/.codex/config.toml:

[mcp_servers.respira-wordpress]
command = "npx"
args = ["-y", "@respira/wordpress-mcp-server"]

Or let add-mcp detect your tool:

npx add-mcp "npx -y @respira/wordpress-mcp-server"

Respira also runs as a hosted remote MCP server with OAuth, so no local Node process is needed. Setup instructions per client are at respira.press/mcp.

3. Add your site

Run the wizard:

npx @respira/wordpress-mcp-server --setup

Or write ~/.respira/config.json yourself:

{
  "sites": [
    {
      "id": "my-site",
      "name": "My WordPress Site",
      "url": "https://yoursite.com",
      "apiKey": "respira_your-api-key",
      "default": true
    }
  ]
}

Restart your AI tool and start editing.

Hitting a client tool limit?

Some MCP clients cap the number of active tools, often at 100. Respira advertises far more than that, so add enabledTools to your config and only those appear in the listing:

{
  "sites": [{ "...": "..." }],
  "preferences": {
    "enabledTools": [
      "respira_read_page",
      "respira_update_page",
      "respira_list_pages",
      "respira_find_element",
      "respira_update_element",
      "respira_build_page",
      "respira_get_site_context",
      "respira_get_builder_info"
    ]
  }
}

Site management tools (respira_list_sites, respira_switch_site, respira_get_active_site) are always included. Unlisted tools still work if called directly. The filter only controls what is advertised.

On top of that, the server filters the tool list by what your site actually runs. A Divi site with no WooCommerce does not see the commerce tools. Detection fails open: if it cannot tell, you get the full list.

17 supported page builders

level is Respira's write depth, not the builder's quality.

Mixed-builder sites are handled per page, not per site.

What the tools cover

The full reference lives in the docs. The families:

All tools use respira_* names. The legacy wordpress_* aliases are deprecated and will be removed.

What the numbers mean

The current counts are on the live tools catalog, counted from the code on every release: MCP tools for the whole product and for every plan, the WooCommerce add-on's tools, and WordPress Abilities. They describe the catalog on a fully enabled site, not what your client will list.

A live tools/list returns fewer than the catalog total, and that is correct behaviour rather than a missing feature. The server context-filters the catalog per site, so Bricks tools never reach an Elementor site and the commerce tools stay hidden without WooCommerce. A block-theme site with no page builder sees fewer core tools still.

The Abilities registry is not context-filtered, so on the same site the abilities total legitimately exceeds the tools total. The two are not directly comparable.

Bundled skills

The package ships Respira's Claude Code skills, which are the recipes that make the tools useful together: page-builder migrations (Divi to Bricks, Elementor to Gutenberg, WPBakery to Bricks, and others), Figma-to-builder conversion, site audits, SEO and AEO passes, and WooCommerce workflows.

npx @respira/wordpress-mcp-server install-skills

Browse the catalog at respira.press/skills.

Safety

Writing to a live production site is the whole problem. The rails:

1. Snapshot before every mutation. Restore with respira_restore_snapshot, compare with respira_diff_snapshots.

2. Duplicate before edit. The original stays untouched while the agent works on a copy.

3. Per-tool governance. Admins enable or disable individual tools from wp-admin. Governance applies to the REST path, the Abilities API path, and WebMCP alike.

4. Read-only mode. Point an agent at a site and let it look without letting it write.

5. Activity log. Every call is recorded and readable from wp-admin and from respira_list_activity.

WordPress AI ecosystem

Respira works with the official WordPress AI stack, not around it.

Inhale is the free companion plugin that registers a small set of Abilities with no Respira account at all, if you want to try the Abilities path before anything else.

Install options

npx

npx -y @respira/wordpress-mcp-server

Zero install, good for trying it. The downside is that the npx cache can corrupt itself after an interrupted install, a disconnected external drive, or antivirus quarantine, and the resulting ENOENT errors are confusing. See Troubleshooting.

Global install (most stable)

npm install -g @respira/wordpress-mcp-server
respira-wordpress-mcp

Avoids the npx cache entirely. The better choice for daily use.

CLI options

Environment variables

export WORDPRESS_URL="https://yoursite.com"
export WORDPRESS_API_KEY="respira_your_key"

RESPIRA_CONFIG_FILE and RESPIRA_CONFIG_B64 are the multi-site alternatives.

Grok Build plugin

This repository is also the source of the Respira plugin for Grok Build. The plugin is small on purpose. It ships two files and nothing else:

• .grok-plugin/plugin.json, the manifest.

• .mcp.json, one MCP server definition: npx -y @respira/wordpress-mcp-server, the same package this README describes.

It has no skills, no commands, no agents, no hooks and no install scripts.

Before first use. Install the Respira for WordPress plugin on the site, then run npx @respira/wordpress-mcp-server --setup once. That writes the site list to ~/.respira/config.json, which the server reads when Grok Build starts it. With no site in that file the server starts with one tool, respira_redeem_token, which takes a setup code from respira.press/dashboard/mcp and writes the site list for you.

Network endpoints the server calls.

Credentials. One Respira site key per site, kept in ~/.respira/config.json on your machine (or WORDPRESS_URL and WORDPRESS_API_KEY for a single site). The key goes only to the site it belongs to, in a request header. The WordPress plugin checks it; the server does not read SSH keys, .env files or other tokens.

Without the plugin. Grok Build can also reach a site directly, one command per site: see respira.press/integrations/grok.

Health check

npx @respira/wordpress-mcp-server --doctor

Checks Node version, config file, site connectivity, plugin version, API compatibility, and available updates, and reports pass or fail per check with something you can act on. Add --json for CI pipelines.

Troubleshooting

Use the full path:

{ "command": "C:\\Program Files\\nodejs\\npx.cmd", "args": ["-y", "@respira/wordpress-mcp-server"] }

Or install globally with npm install -g @respira/wordpress-mcp-server and use { "command": "respira-wordpress-mcp" }.

1. Check the API key at WordPress > Respira > API Keys

2. The URL must include https://

3. The plugin must be activated

4. Check whether your host blocks the REST API

respira_diagnose_connection reports all four in one call.

Some sites have plugin or theme rewrite rules that catch /wp-json/[anything] and rewrite the path to index.php without the ?rest_route= query var. WordPress then 301-redirects to the homepage (you will see x-redirect-by: WordPress in the chain) and the MCP server gets HTML where it expected JSON.

The server auto-detects this, retries the call as ?rest_route=... against the site root, and if that returns JSON it routes every later call the same way for the rest of the session, with one stderr warning on first activation.

If you already know the rewrite shadowing is in play, skip the probe with forceRestRoute:

{
  "sites": [
    {
      "id": "my-site",
      "url": "https://yoursite.com",
      "apiKey": "respira_your-api-key",
      "default": true,
      "forceRestRoute": true
    }
  ]
}

respira_diagnose_connection probes both forms and reports rest_route_fallback_worked, rest_route_fallback_active, and force_rest_route_configured.

1. Restart the AI tool completely, not just the window

2. Validate the JSON syntax in the config file

3. Confirm the config file location for your client

4. Run npx @respira/wordpress-mcp-server --test

If the client caps active tools, see enabledTools above.

The npx cache is corrupted. Common causes: interrupted install, external drive disconnected mid-install, antivirus quarantine, or npm cache clean running while npx was active.

# 1. Switch to a global install, most stable
npm install -g @respira/wordpress-mcp-server
# then use "command": "respira-wordpress-mcp" with no npx wrapper

# 2. Or clear the npx cache and let it rebuild
npx clear-npx-cache
npx -y @respira/wordpress-mcp-server

# 3. Or clear the whole npm cache
npm cache clean --force

Security

API key validation happens server side in the WordPress plugin. The MCP server passes credentials through and does not store or validate them.

Report vulnerabilities to security@respira.press. Full policy in SECURITY.md.

Links

• Website

• Documentation

• Download the plugin

• MCP setup

• Skills catalog

• Abilities

• WooCommerce add-on

• Accessibility scanner add-on

• Support

Where to find Respira

License

MIT © Respira