Summary
Connects AI tooling to WordPress sites through the Respira plugin, exposing 172+ tools for page builder manipulation across 12 builders including Elementor, Divi, and Flatsome. Goes beyond standard REST API wrappers with element-level find/update/remove operations, HTML to native builder conversion, bulk edits across hundreds of pages, and storefront design intelligence. Ships with context-aware tool filtering that narrows the exposed toolset based on your site's detected builder and active plugins. Requires the commercial Respira WordPress plugin and API key. The npm wrapper is MIT licensed, but the underlying plugin infrastructure is proprietary. If you need AI to actually edit page builder content rather than just create posts, this fills that gap.
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →
Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →
Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →
Respira WordPress MCP Server
MCP tools and WordPress Abilities across 17 page builders. The AI infrastructure layer for WordPress.
Element-level editing, full page creation, HTML and Figma to native builder conversion, design directions, site memory, accessibility and security scanning, per-tool governance, snapshots and rollback.
Website • Docs • Plugin • MCP setup • Skills • Support
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.
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.
| Capability | Respira | REST API wrappers |
|---|---|---|
| Page builder support | 17 builders | None |
| Element-level find / update / move / remove | Yes | No |
| Build full pages from a declarative structure | Yes | No |
| Convert HTML or Figma to native builder output | Yes | No |
| Design directions (site-wide art direction) | Yes | No |
| Site memory that persists across agent sessions | Yes | No |
| Accessibility scan and auto-fix | Yes | No |
| Security audit and core hardening | Yes | No |
| Snapshot before every write, rollback anytime | Yes | No |
| Duplicate-before-edit safety | Yes | No |
| Per-tool governance from wp-admin | Yes | No |
| WordPress Abilities API and WebMCP | Yes | Rare |
| WooCommerce (products, orders, inventory, storefront) | Yes (add-on) | No |
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 Code
claude mcp add respira-wordpress -- npx -y @respira/wordpress-mcp-server
Claude Desktop
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"]
}
}
}
Cursor
Create .cursor/mcp.json in your project:
{
"mcpServers": {
"respira-wordpress": {
"command": "npx",
"args": ["-y", "@respira/wordpress-mcp-server"]
}
}
}
Codex, Windsurf, and other clients
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"
ChatGPT and remote clients
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.
| Builder | Level | Notes |
|---|---|---|
| Bricks | Deep | Global classes, theme styles, ACSS, components, query loops, BEM linting |
| Elementor | Full | Native API, runtime control registry |
| Divi | Full | Divi 4 and Divi 5, 40+ module definitions on Divi 5 |
| Oxygen | Full | Classic and Oxygen 6 |
| Gutenberg | Full | Block registry, FSE templates, patterns, navigation |
| Flatsome | Full | Round-trip shortcode editing, 55-element intelligence |
| Beaver Builder | Smart | Tree utility, static schemas |
| Breakdance | Smart | Tree utility, static schemas |
| Brizy | Smart | Tree utility |
| WPBakery | Smart | Tree utility |
| Spectra | Smart | Block target |
| Kadence Blocks | Smart | Block target |
| GenerateBlocks | Smart | Block target |
| GreenShift | Smart | Block target |
| Visual Composer | Smart | Limited write |
| Thrive Architect | Smart | Text edits |
| SeedProd | Smart | Audit only |
Mixed-builder sites are handled per page, not per site.
What the tools cover
The full reference lives in the docs. The families:
| Family | What it does |
|---|---|
| Pages, posts, custom posts | Read and write with builder-aware payloads, outlines, duplicates, translations |
| Element operations | Find, update, move, duplicate, reorder, remove single elements by ID, type, class, or content text |
| Page building | respira_build_page from a declarative structure, plus one-line widget shortcuts (heading, button, image, form, slider, pricing table, and more) |
| Conversion | HTML to native builder with CSS extraction, responsive mapping, and a fidelity score. Figma to Bricks, Divi, Elementor, or Gutenberg via the bundled skills |
| Design directions | Save, apply, activate, export a site-wide art direction. Preview before commit, apply the same direction to another site |
| Design tokens | Create, update, import DTCG tokens, sync a design system into the theme |
| Site memory | respira_remember, respira_forget, respira_list_memory. Facts about the site that survive between agent sessions |
| Playbooks | Named, reusable procedures an agent can create, fetch, and run |
| Snapshots | Automatic before every write, diff two snapshots, restore any of them |
| Analysis | SEO, AEO, readability, RankMath, structured data, images, Core Web Vitals, PageSpeed |
| Accessibility | Scan a page, list scans, apply fixes |
| Security | Security audit, validation, core hardening, debug log reading |
| Theme and templates | FSE templates, template parts, patterns, navigation, theme builder templates, theme file read and write |
| Site structure | Custom post types, taxonomies, ACF field groups, menus, mega menus, terms |
| Media | Upload, sideload from URL, batch metadata updates, Openverse stock image search with auto-attribution |
| Bulk operations | Up to 100 pages per call, with mandatory snapshots |
| Multi-site | List, switch, and act on many sites from one config |
| WooCommerce | Store tools in the paid add-on: catalog, pricing, inventory, orders, storefront design |
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:
- Snapshot before every mutation. Restore with
respira_restore_snapshot, compare withrespira_diff_snapshots. - Duplicate before edit. The original stays untouched while the agent works on a copy.
- 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.
- Read-only mode. Point an agent at a site and let it look without letting it write.
- 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.
| Path | How it works | Requirements |
|---|---|---|
| Standalone MCP (this package) | npx @respira/wordpress-mcp-server | Node 20+, Respira plugin |
| Remote MCP | Hosted endpoint with OAuth, no local process | Respira plugin, account |
| WordPress Abilities API | Every Respira tool registered as an ability, auto-discovered | WP 6.9+, Respira plugin |
| MCP Adapter | Abilities exposed over WP-CLI STDIO | WP 6.9+, MCP Adapter plugin |
| WebMCP | Browser-native MCP via the Chrome Abilities API | Chrome 146+, Respira plugin |
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
| Flag | Alias | Description |
|---|---|---|
--setup | -s | Interactive setup wizard |
--list | -l | List configured sites |
--test | -t | Test the connection |
--doctor | -d | Health diagnostics, add --json for machine-readable output |
--install-config | Write the MCP config for a detected client | |
install-skills | Copy the bundled skills into your local skills directory | |
--stdio | STDIO transport for the MCP Adapter | |
--version | -v | Print the version |
--help | -h | Help |
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.
| Endpoint | Why |
|---|---|
Your own WordPress sites, at /wp-json/respira/v1/ | Every tool call is a request to the Respira plugin on a site in your config file. Nothing else reads or writes site content. |
https://www.respira.press | Exchanging a setup code for the site list, refreshing that list, and one usage record per tool call (tool name, site, version, duration; no page content and no conversation). RESPIRA_USAGE_OPT_OUT=1 turns the usage records off. A bug report is sent only when you ask for one. |
https://registry.npmjs.org | A check for a newer version of the package. RESPIRA_MCP_DISABLE_UPDATE_CHECK=1 turns it off. |
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
Windows: 'npx' is not recognized
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" }.
Connection failed
- Check the API key at WordPress > Respira > API Keys
- The URL must include
https:// - The plugin must be activated
- Check whether your host blocks the REST API
respira_diagnose_connection reports all four in one call.
HTML instead of JSON, or a homepage redirect on every 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.
Tools not showing up
- Restart the AI tool completely, not just the window
- Validate the JSON syntax in the config file
- Confirm the config file location for your client
- Run
npx @respira/wordpress-mcp-server --test
If the client caps active tools, see enabledTools above.
ENOENT errors mentioning /_npx/ or node_modules
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
| Directory | Listing |
|---|---|
| npm | @respira/wordpress-mcp-server |
| Official MCP Registry | io.github.webmyc/respira-wordpress |
| Smithery | smithery.ai |
| Glama | glama.ai/mcp/servers |
| mcp.so | mcp.so |
| cursor.directory | cursor.directory |
License
MIT © Respira
The full tool catalog, counted from the code: respira.press/tools. The AI infrastructure layer for WordPress.
respira.press
Featured
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →Configuration
WORDPRESS_URLWordPress site URL for the single-site env setup.
WORDPRESS_API_KEYsecretRespira API key for the single-site env setup.
RESPIRA_CONFIG_B64secretBase64-encoded multi-site Respira config JSON.
RESPIRA_CONFIG_FILEPath to a Respira config JSON file.
Registryactive
Package@respira/wordpress-mcp-server
TransportSTDIO
AuthRequired
UpdatedJun 9, 2026