Respira for WordPress

What this repo is, what it isn't

This repository is the public listing for the Respira WordPress MCP server. The actual server source ships on npm as @respira/wordpress-mcp-server — that wrapper code is MIT-licensed and you're 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 (1000+ PHP files implementing builder intelligence, snapshots, governance, etc.) is not open source. It's distributed under a commercial license. Free trial available at respira.press; paid plans start at €9/mo.

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

For security reports see SECURITY.md.

Related MCP server: elementor-mcp-agent

What Makes Respira Different

Other WordPress MCP servers wrap the REST API. They can create posts and pages, but they can't touch your page builder content.

Respira includes a WordPress plugin that gives AI native access to 12 page builders — plus element-level precision, full page creation from structure, HTML-to-builder conversion, storefront design intelligence, stock image search, and bulk operations across hundreds of pages.

New in v6.0: Context-Aware Tool Filtering

The MCP server automatically filters the tool list based on your site's detected builder and active plugins. A Divi site without WooCommerce sees ~130 tools instead of ~170. Less noise, faster AI responses, lower token usage. Fail-open: if detection fails, the full list is returned.

Quick Start (3 Minutes)

Step 1: Install the WordPress Plugin

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

Step 2: Configure Your AI Tool

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

Create .cursor/mcp.json in your project:

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

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "respira-wordpress": {
      "command": "npx",
      "args": ["-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"]
    }
  }
}

Step 3: Add Your Site

Create ~/.respira/config.json:

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

Or run the interactive setup wizard: npx @respira/wordpress-mcp-server --setup

Tool Limit? Use enabledTools

Some MCP clients (Antigravity, etc.) have a hard limit on active tools (often 100). Respira exposes 172 tools by default. To stay under the limit, add enabledTools to your config — only those tools will 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 — the filter only controls what's advertised to the client.

Done. Restart your AI tool and start editing.

v6.3 — MCP Protocol Compliance

structuredContent in All Tool Results

Every successful tool response now includes structuredContent — the raw JSON object — alongside the existing content[0].text (stringified JSON). This follows the MCP 2025-06-18 spec. Clients that understand structuredContent get direct programmatic access to tool results without parsing JSON from text. Older clients are unaffected — the content array is still there.

Improved Error Taxonomy

Unknown tool names now return a proper CallToolResult with isError: true and a hint to discover available tools, instead of throwing a protocol-level JSON-RPC error. This lets LLMs self-correct gracefully rather than hitting a hard protocol failure.

v6.0 "Storefront" — What's New

Context-Aware Tool Filtering

The MCP server automatically filters the tool list based on your site's detected builder and active plugins. A Divi site without WooCommerce sees ~130 tools instead of ~170. Less noise, faster AI responses, lower token usage. Fail-open: if detection fails, the full list is returned.

Flatsome UX Builder (Builder #12)

Full round-trip shortcode editing, element-level precision, declarative page creation, and 55-element intelligence. Detected by active theme — mixed-builder sites handled per-page.

15 New WooCommerce Commerce Tools

Storefront design intelligence bridges commerce data and page builder visuals. Bulk pricing, catalog health audits, advanced filtering, natural language product search. Total WooCommerce tools: 36.

Element-Level Operations

Find, update, move, duplicate, and remove individual elements inside any page builder — by ID, type, CSS class, or content text.

respira_find_element({ post_id: 42, identifier_type: "type", identifier_value: "heading" })
respira_update_element({ post_id: 42, identifier_type: "content", identifier_value: "Old Title", updates: { heading: "New Title" } })

Build Full Pages

Create complete pages from a declarative widget structure in one call.

respira_build_page({ title: "Services", structure: [
  { type: "heading", settings: { heading: "Our Services", tag: "h1" } },
  { type: "text", settings: { text: "<p>We build amazing things.</p>" } },
  { type: "button", settings: { text: "Get Started", link: "/contact" } }
]})

HTML-to-Builder Conversion

Convert any HTML into native builder widgets — with CSS extraction, responsive mapping, and a fidelity report.

respira_convert_html_to_builder({ html: "<section>...</section>", options: { title: "Homepage", preserve_tokens: true } })
→ { page_id: 123, fidelity: { score: 92, sections_matched: 14 } }

Stock Images

Search Openverse (Creative Commons) and sideload directly into the Media Library with auto-attribution.

respira_search_stock_images({ query: "mountain landscape", per_page: 10 })
respira_sideload_image({ url: "https://...", caption: "Photo by...", alt: "Mountain" })

Bulk Operations

Apply changes across up to 100 pages in a single call — with mandatory snapshots for rollback.

respira_bulk_pages_operation({ page_ids: [12, 15, 18, 22], operation: { type: "find_and_replace", find: "2025", replace: "2026" } })

27 Widget Shortcuts

One-liner tools to add any widget to a page without building the full structure:

respira_add_heading({ post_id: 42, title: "Hello World", tag: "h2" })
respira_add_button({ post_id: 42, text: "Buy Now", url: "/shop" })
respira_add_image({ post_id: 42, image_url: "https://..." })

12 Supported Page Builders

All Tools

Bricks Deep Intelligence (20 tools) — NEW in v5.4

Element Operations (7 tools) — NEW in v5.2

Page Building (3 tools) — NEW in v5.2

Stock Images (2 tools) — NEW in v5.2

27 Widget Shortcuts — NEW in v5.2

Add any widget to a page in one call:

respira_add_heading · respira_add_text · respira_add_button · respira_add_image · respira_add_video · respira_add_section · respira_add_divider · respira_add_spacer · respira_add_icon · respira_add_icon_list · respira_add_social_icons · respira_add_form · respira_add_map · respira_add_counter · respira_add_progress_bar · respira_add_testimonial · respira_add_tabs · respira_add_accordion · respira_add_toggle · respira_add_alert · respira_add_html · respira_add_menu · respira_add_sidebar · respira_add_search · respira_add_gallery · respira_add_slider · respira_add_pricing_table

Page Builder Tools (6 tools)

Pages & Posts (14 tools)

Snapshots & Rollback (4 tools)

Analysis (8 tools)

Menus (8 tools)

Media (5 tools)

Users & Comments (7 tools)

Taxonomies (5 tools)

Site & Plugins (10 tools)

Multi-Site (3 tools)

WooCommerce Add-on (36 tools)

Available when the WooCommerce add-on is installed. Included free with Studio and Founder plans.

Safe Editing

Every mutation creates a snapshot. Roll back anytime.

1. Snapshot captured before every edit

2. Duplicate-before-edit — original stays untouched

3. Approval workflow — review changes in WordPress admin

4. Rollback — restore any snapshot with respira_restore_snapshot

Tool Governance

Admins can enable/disable individual tools from the WordPress dashboard. Governance applies to both REST API and WebMCP/Abilities API paths.

Multi-Site Support

Manage multiple WordPress sites from one config:

{
  "sites": [
    { "id": "production", "name": "Production", "url": "https://mysite.com", "apiKey": "respira_prod_key", "default": true },
    { "id": "staging", "name": "Staging", "url": "https://staging.mysite.com", "apiKey": "respira_staging_key" }
  ]
}

Switch sites: respira_switch_site({ siteId: "staging" })

For agencies managing many sites, use the hosted setup at respira.press/dashboard/mcp to generate configs and install commands from your account.

Tool Naming: respira_*

All tools use respira_* names (e.g. respira_update_page, respira_find_element). The legacy wordpress_* aliases are deprecated and will be removed in a future release. Update any prompts or workflows that still reference wordpress_* tools.

WordPress AI Ecosystem

Respira works with the official WordPress AI stack:

Quick Install

Three paths — pick the one that matches how you work.

One-command install (recommended)

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

Auto-detects your AI tool (Claude Code, Cursor, Windsurf, Codex, and 9+ more) and writes the correct config file. Powered by add-mcp.

After running, set your environment variables:

# In your shell profile or .env
export WORDPRESS_URL="https://yoursite.com"
export WORDPRESS_API_KEY="respira_your_key"

Interactive setup wizard

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

Walks you through site URL, API key, HTTP auth (for staging sites), and connection testing. Saves config to ~/.respira/config.json.

Manual configuration

See the Quick Start section above for per-tool JSON config examples (Cursor, Claude Code, Claude Desktop, Windsurf).

Installation Options

NPX (Easiest)

npx -y @respira/wordpress-mcp-server

Zero-install. Good for trying it out. Downside: the npx cache can get corrupted (interrupted installs, external drives, antivirus quarantine) and produce confusing ENOENT errors. If you hit any, see Troubleshooting below.

Global Install (Most Stable — Recommended for Daily Use)

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

Avoids the npx cache entirely. Best choice if you're using Respira every day or hit any npx-related errors.

Interactive Setup Wizard

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

CLI Options

Environment Variables

export WP_SITE_URL=https://your-site.com
export WP_API_KEY=respira_your-api-key

Health Check

Verify your setup is working end-to-end:

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

Checks Node.js version, config file, site connectivity, plugin version, API compatibility, and available updates. Reports pass/fail for each check with actionable messages.

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

Machine-readable output for CI/CD pipelines or AI tool diagnostics.

Troubleshooting

Use the full path:

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

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

1. Check API key: WordPress > Respira > API Keys

2. URL must include https://

3. Plugin must be activated

4. Check if hosting blocks REST API

Some WordPress 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. The result: WordPress's redirect_canonical() 301-redirects the request to the homepage (you'll see x-redirect-by: WordPress on the redirect chain), and the MCP server gets HTML back where it expected JSON.

Since v6.11.2, the MCP server auto-detects this and transparently retries the call as ?rest_route=... against the site root. If the retry returns JSON, it sets a per-session sticky flag and routes every subsequent call directly through ?rest_route=, with one stderr warning on first activation.

For sites where you know this rewrite shadowing is in play, you can skip the pretty-permalink probe entirely by adding forceRestRoute: true to the site config:

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

Run wordpress_diagnose_connection for triangulation — it now probes both the pretty path and the ?rest_route= form, and reports rest_route_fallback_worked, rest_route_fallback_active, and force_rest_route_configured.

1. Restart your AI tool completely

2. Validate JSON syntax in config file

3. Check config file location

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

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

Fix with one of these (in order of preference):

# 1. Switch to global install — most stable, recommended
npm install -g @respira/wordpress-mcp-server
# then in your AI client config, use:
#   "command": "respira-wordpress-mcp"   (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 nuke the entire npm cache
npm cache clean --force

Security

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

Report vulnerabilities to security@respira.press.

Links

• Website

• Documentation

• Download Plugin

• WooCommerce Add-on

• Support

Where to Find Respira

License

MIT © Respira