Connecting Your WordPress Site to AI Clients via Astra MCP

Model Context Protocol (MCP) lets AI clients like Claude, Cursor, and ChatGPT directly interact with your WordPress site — reading content, managing settings, and taking actions on your behalf. Astra exposes two MCP endpoints that you can connect to any supported AI client.

What’s the Difference: Astra Only vs Global?

	Astra Only	Global
What it exposes	Astra theme settings and controls only	All WordPress content (posts, pages, plugins, settings, etc.)
Best for	Managing your Astra theme via AI	Full site management via AI
Endpoint	{site-url}/wp-json/astra/v1/mcp	{site-url}/wp-json/mcp/mcp-adapter-default-server

Start with Astra Only if you just want to control your theme. Use Global if you want your AI client to manage your entire site.

Prerequisite

Before you begin, make sure you have:

• Astra theme installed and active on your WordPress site
• Node.js v20 or v22 installed on your computer (check by running node --version in your terminal)
• An AI client that supports MCP (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, or ChatGPT)

Step 1: Create a WordPress Application Password

MCP uses Application Passwords to authenticate securely — you don’t share your main WordPress password.

1. Log in to your WordPress admin dashboard
2. Go to Users → Profile (or navigate directly to {site-url}/wp-admin/profile.php#application-passwords-section)
3. Scroll down to the Application Passwords section
4. Enter a name for the password (e.g. Claude MCP) and click Add New Application Password
5. Copy the generated password — you won’t be able to see it again

Note: Application Passwords are available in WordPress 5.6 and later. Make sure your site is not blocking Application Password authentication via a security plugin.

Step 2: Get Your MCP Config from Astra

1. In your WordPress admin, go to Astra → Settings → MCP
2. Choose your mode — Astra Only or Global — using the tabs
3. You’ll see a JSON config block pre-filled with your site URL and username

It looks like this:

{
  "mcpServers": {
    "yoursite-astra": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://yoursite.com/wp-json/astra/v1/mcp",
        "WP_API_USERNAME": "YOUR-WP-USERAME",
        "WP_API_PASSWORD": "YOUR-APPLICATION-PASSWORD"
      }
    }
  }
}

Replace YOUR-APPLICATION-PASSWORD with the password you generated in Step 1.

---

Step 3: Add the Config to Your AI Client

Claude Desktop

Config file location:

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

1. Open your terminal and run the following — then paste the output back into Claude so it can detect your Node.js setup:
   • which npx && node --version && echo $PATH
2. Open the config file in a text editor (create it if it doesn’t exist)
3. Merge the MCP server entry into the mcpServers object — do not overwrite other existing entries
4. Set "command" to the full path from which npx (e.g. /opt/homebrew/bin/npx)
5. Add a "PATH" key to "env" with your actual $PATH output — MCP servers don’t inherit your shell’s PATH
6. Save the file and restart Claude Desktop

Example final config:

{
  "mcpServers": {
    "yoursite-astra": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://yoursite.com/wp-json/astra/v1/mcp",
        "WP_API_USERNAME": "admin",
        "WP_API_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Claude Code

Config file: .mcp.json in your project root (or global ~/.claude/mcp.json)

1. In your terminal, run:
   • which npx && node --version && echo $PATH
2. Claude Code can run terminal commands directly — paste the prompt from Astra into Claude Code, and it will detect your setup automatically
3. Merge the server entry and restart

Cursor

Config file: .cursor/mcp.json in your project root

1. Open your terminal and run:
   • which npx && node --version && echo $PATH
2. Open or create .cursor/mcp.json
3. Merge the server entry using the full npx path and your $PATH
4. Restart Cursor

Windsurf

Config file: ~/.codeium/windsurf/mcp_config.json

1. Run which npx && node --version && echo $PATH in your terminal
2. Open or create the config file
3. Merge the server entry with the full npx path and your $PATH
4. Restart Windsurf

VS Code (with GitHub Copilot Agent)

Config file: .vscode/mcp.json in your project root

Note: VS Code uses a "servers" key instead of "mcpServers".

{
  "servers": {
    "yoursite-astra": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://yoursite.com/wp-json/astra/v1/mcp",
        "WP_API_USERNAME": "admin",
        "WP_API_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

ChatGPT

ChatGPT uses a connector URL instead of a JSON config file.

1. Open ChatGPT and go to Settings → Connectors → Add Connector
2. Paste your MCP endpoint URL:
   • Astra Only: https://yoursite.com/wp-json/astra/v1/mcp
   • Global: https://yoursite.com/wp-json/mcp/mcp-adapter-default-server
3. Set authentication to HTTP Basic Auth
4. Enter your WordPress username and the Application Password from Step 1
5. Save the connector

For more details, see: https://developers.openai.com/apps-sdk/deploy/connect-chatgpt

Using the AI Setup Prompt (Easiest Method)

Not sure how to edit config files? Use the ✨ sparkle button in the Astra MCP panel to copy a ready-made prompt, then paste it directly into your AI client. The AI will:

1. Ask which client you use and your OS
2. Ask for your Application Password
3. Locate the correct config file for your setup
4. Ask you to run which npx && node --version && echo $PATH and paste the output
5. Write the correct config with your actual paths
6. Confirm everything was added correctly

Troubleshooting

MCP server not showing up in my AI client

• Make sure you restarted the AI client after editing the config
• Verify the JSON is valid (no trailing commas, correct brackets)
• Check that "command" uses the full absolute path to npx, not just npx

Authentication errors

• Double-check the Application Password — it should include spaces (e.g. xxxx xxxx xxxx xxxx xxxx xxxx)
• Make sure the username matches exactly what’s in your WordPress user profile
• Verify your site URL ends without a trailing slash in WP_API_URL

Node.js version errors

• Run node --version — you need v20 or v22
• Use nvm to install the correct version: nvm install 22

“npx not found” or command errors

• The "command" field must be the full path from which npx, not just npx
• Add the "PATH" key to "env" so the MCP server can find Node.js at runtime

Site is behind a local domain (e.g. .local)

• Local sites work fine — just make sure the AI client is running on the same machine
• Local URLs like http://mysite.local won’t be reachable from ChatGPT (cloud-based), use a public URL for ChatGPT

Further Reading

• WordPress MCP Adapter — WordPress Developer Blog
• ChatGPT Connector Setup — OpenAI
• Model Context Protocol — Official Docs