Connecting Your WordPress Site to AI Clients via Astra MCP

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

Requirements

Note: This feature is available in the free version of Astra.

• Astra theme: version 4.13.0 or newer, installed and active
• WordPress: Version 6.9 or newer. If you’re using an older version, install and activate the WordPress Abilities API polyfill plugin.
• WP MCP Adapter plugin: Installed and active. You can download the ZIP file from the Github here.
• Availability: Free Astra theme. Astra Pro does not add any additional abilities.
• Node.js: v20 or v22 installed on your computer (check by running node –version in your terminal)
• AI client: Claude Code, Claude Desktop, Cursor, Windsurf, or VS Code
• User permissions: Most Astra abilities require the edit_theme_options capability. Some post-related abilities instead require the appropriate post editing permissions (edit_posts and edit_post). Administrators have these permissions by default.

What’s the Difference: Astra Only vs Global?

	Astra Only	Global
What it exposes	Astra theme settings and controls only	Astra theme settings plus WordPress core abilities (posts, pages, plugins, settings, etc.)
Best for	Managing the Astra theme via AI	Full site management via AI, as WordPress core abilities become available
Endpoint	{site-url}/wp-json/astra/v1/mcp	{site-url}/wp-json/mcp/mcp-adapter-default-server
Required capability	edit_theme_options	Depends on the WordPress core ability being called

Start with Astra Only to control just the theme. Use Global to let an AI client manage the entire site.

Step 1: Create a WordPress Application Password

MCP uses Application Passwords to authenticate securely, so the main WordPress password is never shared with an AI client.

1. Log in to the 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 (for example, Claude MCP) and click Add New Application Password.
5. Copy the generated password. It won’t be shown again.

Step 2: Get the MCP Config from Astra

1. In the WordPress admin, go to Astra → Settings → MCP.
2. Turn on Enable Abilities and Enable MCP Server.
3. If you want AI clients to update Astra settings, also turn on Enable Edit Abilities. Leave it disabled if you only need read access.
4. Choose a mode, Astra Only or Global, using the tabs.
5. A JSON config block appears, pre-filled with the 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-USERNAME",
        "WP_API_PASSWORD": "YOUR-APPLICATION-PASSWORD"
      }
    }
  }
}

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

Step 3: Add the Config to an 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 a terminal and run the following, then paste the output back into Claude so it can detect the 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 (for example, /opt/homebrew/bin/npx).
5. Add a “PATH” key to “env” with the actual $PATH output, since MCP servers don’t inherit the 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 the project root, or a global ~/.claude/mcp.json.

1. In a 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 the setup automatically.
3. Merge the server entry and restart.

---

Cursor

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

1. Open a 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 the $PATH output.
4. Restart Cursor.

---

Windsurf

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

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

---

VS Code (with GitHub Copilot Agent)

Config file: .vscode/mcp.json in the 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"
      }
    }
  }
}

---

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 an AI client. The AI will:

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

---

Expected Outcome

Once connected, the AI client shows the MCP server as active (for example, Claude Desktop lists it under Developer → Local MCP servers with a running status). Asking the AI client to read or change an Astra setting, for example, “What’s my current global color palette in my WordPress site example.com?”, should return live data from the connected site instead of a generic answer.

Available Abilities (Astra Only Mode)

Astra Only mode exposes 74 abilities covering Astra’s theme settings, grouped by category below. Each ability is read (retrieves a setting), write (updates a setting), or list (returns available options). All abilities require the edit_theme_options capability.

Performance

Ability	Type	Description
astra/get-performance / update-performance	Read / Write	Performance settings
astra/get-font-google-local / astra/update-font-google-local	Read / Write	Local Google Fonts loading
astra/get-font-preload-local / astra/update-font-preload-local	Read / Write	Font preloading
astra/flush-font-local	Write	Deletes locally cached Google Font files from the server. See Safety Notes.

Typography

Ability	Type	Description
astra/get-font-body / update-font-body	Read / Write	Body font family, weight, size, spacing
astra/get-font-heading / astra/update-font-heading (singular)	Read / Write	Global headings font
astra/get-font-h1 through h6 / update-font-h1 through h6	Read / Write	Font settings for individual heading levels
astra/list-font-family	List	Available font families
astra/get-paragraph-margin / update-paragraph-margin	Read / Write	Paragraph margin spacing
astra/get-link-underline / astra/update-link-underline	Read / Write	Link underline behavior

Colors

Ability	Type	Description
astra/get-global-palette / update-global-palette	Read / Write	Site-wide color palette preset and custom colors
astra/get-color-background / astra/update-color-background	Read / Write	Background color settings
astra/update-theme-color	Write	Updates the primary theme color

Container

Ability	Type	Description
astra/get-container-layout / update-container-layout	Read / Write	Container layout settings
astra/list-container-setting	List	Available container layout options

Buttons

Ability	Type	Description
astra/get-global-buttons / astra/update-global-buttons (plural)	Read / Write	Global button styles

Header Builder

Ability	Type	Description
astra/get-header-builder / update-header-builder	Read / Write	Header builder layout and zones
astra/get-header-builder-design / update-header-builder-design	Read / Write	Header design settings
astra/update-header-component	Write	Updates a specific header component
astra/list-header-builder-setting	List	Available header widgets and settings

Transparent Header

Ability	Type	Description
astra/get-transparent-header / update-transparent-header	Read / Write	Transparent header settings

Footer Builder

Ability	Type	Description
astra/get-footer-builder / update-footer-builder	Read / Write	Footer builder layout and zones
astra/get-footer-builder-design / update-footer-builder-design	Read / Write	Footer design settings

Blog and Post Types

Ability	Type	Description
astra/get-blog-archive / update-blog-archive	Read / Write	Blog archive layout settings
astra/get-single-post / update-single-post	Read / Write	Single post layout settings
astra/get-single-page / update-single-page	Read / Write	Single page layout settings

Site Identity

Ability	Type	Description
astra/get-site-title-logo / update-site-title-logo	Read / Write	Site title, tagline, and logo

Breadcrumb

Ability	Type	Description
astra/get-breadcrumb / update-breadcrumb	Read / Write	Breadcrumb display settings

Post Meta

Ability	Type	Description
astra/get-post-meta / update-post-meta	Read / Write	Astra’s per-post layout settings

Sidebar

Ability	Type	Description
astra/get-sidebar / update-sidebar	Read / Write	General sidebar settings
astra/get-sidebar-layout / update-sidebar-layout	Read / Write	Sidebar layout (left/right/none)
astra/get-sidebar-style / update-sidebar-style	Read / Write	Sidebar style (boxed/unboxed)
astra/get-sidebar-width / update-sidebar-width	Read / Write	Sidebar width
astra/get-sidebar-sticky / astra/update-sidebar-sticky	Read / Write	Sticky sidebar behavior

Scroll to Top

Ability	Type	Description
astra/get-scroll-to-top / update-scroll-to-top	Read / Write	Scroll-to-top button settings

For Global mode abilities covering WordPress core content (posts, pages, and so on), see the WordPress core Abilities API progress tracked at github.com/WordPress/ai/issues/40.

Example User Flows

These examples show how a request in plain language maps to Astra MCP abilities behind the scenes.

Recommended Workflow

To avoid unintended changes, it’s recommended to follow this order:

1. Read before writing. Use a get-* or list-* ability to check the current setting before calling the matching update-* ability.
2. Confirm target values with the AI client before it applies a write ability, especially for site-wide settings like the color palette or typography.
3. Review changes in the Customizer after an AI client makes updates, since changes made through MCP take effect immediately.

Safety Notes

All Astra Only abilities require the edit_theme_options capability. There’s no separate, higher permission tier for higher-impact changes, read and write abilities use the same capability requirement.

One ability permanently deletes files: astra/flush-font-local deletes locally cached Google Font files from the server. This can’t be undone, though fonts are automatically re-downloaded the next time they’re needed. It’s recommended to confirm with the AI client before allowing this ability to run.

Example Requests

Reading the current body font settings (astra/get-font-body):

{
  "success": true,
  "message": "Body font settings retrieved.",
  "data": {
    "font_family": "inherit",
    "font_weight": "400",
    "font_size": { "desktop": 15, "tablet": 15, "mobile": 15 },
    "font_extras": { "line-height": 1.6, "letter-spacing": 0 }
  }
}

Updating the global color palette (astra/update-global-palette):

{
  "preset": "Oak",
  "palette_id": "palette_1",
  "colors": {
    "0": "#007cba",
    "1": "#ffffff",
    "2": "#1e1e1e"
  },
  "set_as_current": true
}

Valid preset values: Oak, Lily, Viola, Cedar, Willow, Rose, Sage, Flare, Maple, Birch, Dark.

Every ability response follows the same structure: a success boolean, a message, and a data object with the result. If an ability fails, success is false and the response includes a message and a suggestion for resolving the issue.

Troubleshooting

MCP server not showing up in the AI client

• Make sure the AI client was restarted 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 (for example, xxxx xxxx xxxx xxxx xxxx xxxx).
• Make sure the username matches exactly what’s in the WordPress user profile.
• Verify the site URL ends without a trailing slash in WP_API_URL.

Node.js version errors

• Run node --version, v20 or v22 is required.
• 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 (for example, .local)

• Local sites work fine as long as the AI client is running on the same machine.
• Local URLs like http://mysite.local won’t be reachable from a cloud-based tool; use a public URL instead.

Notes or Limitations

• Astra Pro does not currently expose any additional MCP abilities beyond the free Astra theme.
• ChatGPT cannot connect to the Astra MCP server due to a current OpenAI-side limitation.
• Global mode’s coverage of WordPress core content actions depends on WordPress core’s own Abilities API rollout, which is still in progress.

Further Reading

• WordPress MCP Adapter — WordPress Developer Blog
• Model Context Protocol — Official Docs

FAQ