wp-mcp-server

An MCP (Model Context Protocol) server that lets an AI design agent connect to any WordPress site, inspect its real rendered CSS/JS/theme, and create/update pages. It is a standalone, reusable server — nothing in it is tied to a specific WordPress install; the target site is configured entirely through environment variables at runtime.

It combines two things:

• WordPress's native REST API (wp/v2/pages), authenticated with Application Passwords.

• A small companion plugin, wp-mcp-theme-bridge (bundled in this repo under wordpress-plugin/wp-mcp-theme-bridge/), that exposes two extra read-only routes (wp-mcp-bridge/v1/theme-styles and wp-mcp-bridge/v1/asset-content) so the agent can see exactly which CSS/JS a page actually renders — theme-agnostic, since it parses the real rendered HTML instead of relying on theme.json (many themes, including Astra, resolve colors at PHP runtime, not in static files).

Prerequisites

• Node.js >= 18 (for global fetch)

• A WordPress site with:

  • Application Passwords enabled (WordPress core, no plugin needed for the page tools)

  • The wp-mcp-theme-bridge plugin installed and activated, if you want get_theme_styles / get_asset_content to work (see below)

Related MCP server: wp-mcp

Installing the WordPress-side plugin

get_theme_styles and get_asset_content need wp-mcp-theme-bridge running on the target WordPress site — it's a regular plugin (not a must-use/mu-plugins one), so it needs manual activation like any other plugin:

1. Copy wordpress-plugin/wp-mcp-theme-bridge/ from this repo into that site's wp-content/plugins/ directory (git, SFTP, your host's file manager — whatever you already use to deploy). The folder must keep its name (wp-mcp-theme-bridge/) with wp-mcp-theme-bridge.php directly inside it.

2. In wp-admin → Plugins, find WP MCP Theme Bridge and activate it.

3. Verify it: curl -H "Authorization: Basic <base64 user:app-password>" "https://your-site.com/wp-json/wp-mcp-bridge/v1/theme-styles?path=/" should return JSON, not a 404.

The four page tools (list_pages, get_page, create_page, update_page) work without this plugin — it's only required for the two theme-inspection tools.

Install & build

cd mcp-server
npm install
npm run build

This compiles src/ to dist/. npm start runs the built server (dist/index.js) directly over stdio — this is what an MCP client will actually spawn.

Generating a WordPress Application Password

1. Log into wp-admin as a user with the edit_pages capability (e.g. an Editor or Administrator).

2. Go to Users → Profile.

3. Scroll to Application Passwords, give it a name (e.g. wp-mcp-server), and click Add New Application Password.

4. Copy the generated password immediately — WordPress only shows it once. It's fine to keep the spaces WordPress displays it with; Basic Auth works either way.

Configuration (environment variables)

Copy .env.example to .env and fill it in for local development (.env is git-ignored and is not read automatically by the built server — it's there for your own tooling/reference; pass the variables through your process environment or your MCP client's env config, as shown below).

The server validates these three variables at startup and exits with a clear error message if any is missing.

Registering with an MCP client

From a local checkout (development)

{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": ["/absolute/path/to/wp-mcp-server/dist/index.js"],
      "env": {
        "WORDPRESS_URL": "http://localhost:8080",
        "WORDPRESS_USERNAME": "your-wp-username",
        "WORDPRESS_APP_PASSWORD": "your-application-password"
      }
    }
  }
}

Point args at the built dist/index.js for the WordPress site you want this instance of the server to manage. To manage a different site, register another entry with different env values — the server itself is stateless and reusable.

Straight from GitHub (no local checkout, no npm registry)

This package isn't published to the npm registry. Any MCP client that can run a command can still add it directly from the git repository — npx clones it, installs dependencies, runs prepare (which builds dist/), then runs the bin entry, all in one shot:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "github:eimon/wp-mcp"],
      "env": {
        "WORDPRESS_URL": "https://your-site.example.com",
        "WORDPRESS_USERNAME": "your-wp-username",
        "WORDPRESS_APP_PASSWORD": "your-application-password"
      }
    }
  }
}

With the Claude Code CLI specifically:

claude mcp add wordpress-<site-name> \
  -e WORDPRESS_URL=https://your-site.example.com \
  -e WORDPRESS_USERNAME=your-wp-username \
  -e WORDPRESS_APP_PASSWORD='xxxx xxxx xxxx xxxx xxxx xxxx' \
  -- npx -y github:eimon/wp-mcp

Pin to a tag or commit (github:eimon/wp-mcp#v0.1.0) once you cut a release, so a client's config doesn't silently pick up unreleased changes from the default branch.

Available tools

Verifying it works: the smoke test

There's no human clicking through this — scripts/smoke-test.ts is the verification. It spawns the built server as a child process using the official MCP SDK's Client + StdioClientTransport, calls tools/list, then exercises get_theme_styles and list_pages against a real WordPress instance:

npm run build
WORDPRESS_URL=http://localhost:8080 \
WORDPRESS_USERNAME=your-wp-username \
WORDPRESS_APP_PASSWORD=your-application-password \
npm run smoke-test

It exits non-zero and prints the failure if any tool errors or an expected shape isn't found.

Troubleshooting

Silent rest_not_logged_in / 401 errors despite correct credentials

On a non-HTTPS WordPress site, Application Passwords are silently disabled unless wp_get_environment_type() returns 'local' — WordPress core requires is_ssl() || wp_get_environment_type() === 'local' before it will accept them (wp_is_application_passwords_supported()). If you point this server at your own local (non-HTTPS) WordPress install and get 401 rest_not_logged_in even though the username and Application Password are correct, this is almost certainly the cause.

Fix it by setting the environment type to local, e.g. in wp-config.php:

define( 'WP_ENVIRONMENT_TYPE', 'local' );

(or the equivalent WORDPRESS_CONFIG_EXTRA env var if you're running the official wordpress Docker image.)

get_theme_styles / get_asset_content return 404

These two tools depend on the wp-mcp-theme-bridge plugin (bundled in this repo under wordpress-plugin/) being installed and activated on the target site — see "Installing the WordPress-side plugin" above. If it isn't, only the four page tools (list_pages, get_page, create_page, update_page) will work.

403 / capability errors

Both bridge routes and the page-write routes require the authenticated user to have the edit_pages capability (Editor role or above). Application Passwords authenticate as that WordPress user, so permissions follow normal WordPress role rules.