Configuration Guide

This page focuses on the standalone Respira MCP server configuration path.

If you want the WordPress-native stack instead, see WordPress AI Stack Compatibility. If you want the curated Elementor browser workflow, see Elementor Angie.

Quick Setup (Dashboard Recommended)

Open respira.press → Dashboard → MCP Setup and choose:

• Download config file per client
• Copy one-time install command
• Copy AI setup prompt

This is the recommended flow for multi-site and stacked plans.

Local CLI Setup

The fastest way to configure Respira is using the interactive setup wizard with @respira/wordpress-mcp-server:

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

The wizard will guide you through configuration, validate your connection, and generate all config files automatically.

CLI Options

npx @respira/wordpress-mcp-server --setup   # Run setup wizard
npx @respira/wordpress-mcp-server --list    # List configured sites
npx @respira/wordpress-mcp-server --test    # Test connection to default site
npx @respira/wordpress-mcp-server --help    # Show help

Cursor

Configure Respira to work with Cursor.

Manual Configuration

Create or edit .cursor/mcp.json in your project root:

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

Then create your site configuration by running:

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

Or manually create ~/.respira/config.json:

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

Restart Cursor to load the MCP server configuration.

Codex

Configure Respira to work with Codex.

Add to Codex MCP configuration:

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

Claude Code

Configure Respira to work with Claude Code (CLI) or Claude Desktop.

For Claude Code (CLI)

Add to ~/.claude.json:

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

For Claude Desktop

Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the same configuration shown above.

Then create your site configuration:

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

Restart Claude Code or Claude Desktop to load the configuration.

Claude Cowork

Configure Respira to work with Claude Cowork, the AI editing surface inside the Claude desktop app. The Cowork plugin is bundled with eight slash commands and 30 skills for WordPress editing without writing prompts.

Install the Cowork plugin

In Claude:

1. Open Customize > Plugins > Add Custom Plugin.
2. Paste https://github.com/respira-press/cowork-plugin-wordpress.
3. Click Install.

(Marketplace approval pending with Anthropic. Until it lands, install directly from the GitHub repo.)

Connect your sites

Cowork reads the same ~/.respira/config.json file that the Claude Desktop bundle uses. If Claude Desktop is already set up on this machine, you are done. Open a new Cowork chat and every site is immediately editable.

If this is a fresh machine, the fastest path is the one-click flow from your dashboard.

Option A: Open in Cowork (one click). Open respira.press/dashboard/mcp, find the Cowork card, click Open in Cowork. Your browser opens a fresh Cowork chat with a one-time setup token pre-filled in the composer. Hit send. Claude calls respira_redeem_token, the MCP server writes ~/.respira/config.json for you, and reports back how many sites are connected. The token expires in 5 minutes and self-invalidates on use.

Option B: Copy the setup prompt. On the same card, click Copy setup prompt. The pre-filled prompt is copied to your clipboard. Paste into any Cowork chat where the Respira plugin is installed and send. Same outcome as Option A, useful when your browser blocks the claude:// scheme.

Option C: Download the config file directly. On the same card, click Download config. Save the resulting config.json to ~/.respira/config.json on your computer. Open a new Cowork chat. The plugin picks up the file on startup.

If you prefer to be walked through it in chat, run /respira:connect-site inside Cowork.

What is bundled

• 8 slash commands including /respira:connect-site, /respira:edit-page, /respira:undo-last-change, /respira:audit-site, /respira:duplicate-page, /respira:preview-changes, /respira:add-section, /respira:help.
• 30 skills that auto-activate when the conversation matches: safety, page-builder detection, multi-site context, mobile experience report, technical debt audit, WooCommerce health check, SEO + AEO amplifier, internal link builder, image optimizer, 16 builder-to-builder migration recipes, and more.
• 1 visual reviewer sub-agent that shows what changed after each edit.

Troubleshooting

If the MCP server fails to start, Cowork shows "MCP server still connecting" indefinitely with no visible error. Check for a diagnostic file at ~/.respira/last-startup-error.txt. the server writes the actual failure there on startup crashes (added in @respira/wordpress-mcp-server 6.11.5). Common causes:

• ~/.respira/config.json missing or malformed. Re-download from the respira.press dashboard.
• API key in the config has been revoked or rotated. Re-download the config to get the current key.
• The site is unreachable from your machine (firewall, maintenance mode, login wall).

Windsurf

Configure Respira to work with Windsurf by Codeium.

Add to your Windsurf MCP configuration:

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

Then run npx @respira/wordpress-mcp-server --setup to create your site configuration.

Multiple WordPress Sites

You can configure multiple WordPress sites using the setup wizard or manually.

Option 1: Use dashboard MCP setup (recommended)

Use respira.press → Dashboard → MCP Setup to generate account-wide multi-site config. This includes all eligible connected sites across stacked plans.

Option 2: Use the Setup Wizard

Run npx @respira/wordpress-mcp-server --setup and follow prompts to add sites.

Option 3: Manual Configuration

Create or edit ~/.respira/config.json:

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

Managing Sites

• --list - View all configured sites
• --test - Test connection to the default site
• Use wordpress_switch_site in your AI assistant to switch between sites

Troubleshooting

MCP Server Not Connecting

• Run npx @respira/wordpress-mcp-server --test to test your connection
• Check that Node.js 18+ is installed: node --version
• Verify your config file exists at ~/.respira/config.json
• Run npx @respira/wordpress-mcp-server --list to see configured sites

API Key Not Working

• API key may start with respira_ (plugin key) or respira_site_ (dashboard-issued site token)
• Verify the API key is active in WordPress admin (Respira → API Keys)
• Ensure your WordPress site URL includes https://
• Check that the Respira plugin is installed and activated on WordPress

Windows: 'npx' Not Recognized

• Use full path: C:\Program Files odejs px.cmd
• Or install globally: npm install -g @respira/wordpress-mcp-server

Need More Help?

Visit our Troubleshooting page or contact word@respira.press.

Next Steps