Respira WordPress MCP Server

180+ MCP tools. 12 page builders. Context-aware tool filtering. The AI infrastructure layer for WordPress.
Element-level editing, full page creation, HTML-to-builder conversion with rendering fidelity validation, per-site tool governance, storefront design intelligence, stock images, bulk operations — all through one MCP server.

Website • Docs • Plugin • Support • WooCommerce Add-on

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.

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

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

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

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

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

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

# 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 [email protected].

Links

• Website
• Documentation
• Download Plugin
• WooCommerce Add-on
• Support

Where to Find Respira

License

MIT © Respira

172 tools. 12 builders. The AI infrastructure layer for WordPress.
respira.press