Connects to any WordPress site via its REST API (authenticated with Application Passwords) to list, retrieve, create, and update pages, and — with the bundled wp-mcp-theme-bridge plugin — inspect a page path's real rendered theme name, stylesheets, scripts, inline CSS/JS, and fetch the raw content of same-origin CSS/JS assets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@wp-mcp-server inspect my homepage's rendered CSS and update the page to match the theme"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
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
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:
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.
In wp-admin → Plugins, find WP MCP Theme Bridge and activate it.
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.
cd mcp-server
npm install
npm run buildThis 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.
Log into wp-admin as a user with the edit_pages capability (e.g. an Editor or
Administrator).
Go to Users → Profile.
Scroll to Application Passwords, give it a name (e.g. wp-mcp-server), and click
Add New Application Password.
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.
Variable | Description |
| Base URL of the WordPress site, no trailing slash (e.g. |
| WordPress username to authenticate as |
| The Application Password generated above |
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.
{
"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.
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-mcpPin 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.
Tool | Description |
| List/search WordPress pages ( |
| Fetch a single page by ID |
| Create a new page ( |
| Update an existing page by ID (same fields as create, all optional) |
| Inspect a page path's real rendered theme name, stylesheets, scripts, inline CSS/JS |
| Fetch the raw text content of a same-origin CSS/JS asset URL |
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-testIt exits non-zero and prints the failure if any tool errors or an expected shape isn't found.
rest_not_logged_in / 401 errors despite correct credentialsOn 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 404These 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.
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.
Create a new page via POST /wp-json/wp/v2/pages. content is an HTML string. Requires edit_pages capability on the authenticated user.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional meta fields object to attach to the page. | |
| title | Yes | The page title. | |
| status | No | Publication status. Defaults to "draft" if omitted. | |
| content | Yes | The page body as an HTML string. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the HTTP method/endpoint and the auth capability requirement, but says nothing about side effects, whether the page is immediately live, rate limits, or failure modes for duplicate titles.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and endpoint, then the format hint and the capability requirement. Every sentence carries information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and a nested meta object, the description does not indicate what is returned (e.g., the new page ID needed for later updates) or how meta fields are handled in practice. It covers the essentials but leaves a real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description restates that content is an HTML string, which the schema already documents, and adds no format or syntax detail beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new page') plus the backing endpoint (POST /wp-json/wp/v2/pages), which clearly separates it from the get/list/update siblings. It stops short of explicitly naming those alternatives, but the intent is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The prerequisite 'Requires edit_pages capability on the authenticated user' implicitly tells the agent when this tool is viable, but there is no explicit guidance on when to use create_page versus update_page or what happens if the page already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the raw text content of a CSS or JS asset URL discovered via get_theme_styles. The URL must belong to the same host as the connected WordPress site (enforced server-side as a basic SSRF guard). Calls the site-local wp-mcp-bridge/v1 REST route.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Absolute URL of the CSS/JS asset to fetch, as returned by get_theme_styles. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the server-side SSRF guard and the wp-mcp-bridge/v1 REST route, but says nothing about the response shape beyond 'raw text', authentication requirements, size limits, or error behavior (e.g. what happens if the URL is off-host).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the verb and resource. The REST-route detail is mildly technical but plausibly useful context; no filler sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description covers what is fetched, where the URL comes from, and the host constraint. It does not explain the return format or failure modes, but the essentials an agent needs to call it correctly are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning: the URL must originate from get_theme_styles and must be same-host, a constraint not encoded in the schema format/description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Fetch) and resource (raw text content of a CSS/JS asset URL), and explicitly ties the URL provenance to the sibling tool get_theme_styles. An agent can distinguish this from get_theme_styles and the page tools without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly establishes the context of use: the URL must come from get_theme_styles and must be on the connected site's host. It does not state explicit exclusions or alternatives, but the prerequisite and constraint give strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single page by ID via GET /wp-json/wp/v2/pages/?context=edit. Returns both content.rendered (compiled HTML/output) and content.raw (the actual stored source — e.g. real Fusion Builder shortcodes on an Avada site, or Gutenberg block markup) — use content.raw to learn a site's real authoring syntax before writing new content.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The numeric WordPress page ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers the key non-obvious behavior: the response contains both content.rendered (compiled) and content.raw (stored source, e.g. Avada shortcodes or Gutenberg markup). It omits that context=edit typically requires authentication/permissions and says nothing about 404 or invalid-ID behavior, which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and endpoint, then the rendered/raw distinction and its practical use. Every clause earns its place, though the dash-embedded middle clause packs multiple ideas into one long sentence where a shorter break would read better.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must explain returns, and it does so well by contrasting content.rendered and content.raw. The remaining gap is auth/permission behavior implied by context=edit, which an agent would need to know before calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'id' parameter is fully documented there as the numeric WordPress page ID. The description restates 'by ID' but adds no format, range, or lookup detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a single page by ID'), which immediately separates it from the plural list_pages sibling. The endpoint and context=edit are given inline, so the agent knows exactly what will be retrieved without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives real usage direction: 'use content.raw to learn a site's real authoring syntax before writing new content,' which ties this read tool to the create_page/update_page siblings. It stops short of explicitly naming those siblings or stating when-not to use it, so it is context-rich but not a full routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the actual rendered HTML of a page path on the connected WordPress site and return its theme name plus the stylesheet URLs, script URLs, inline CSS and inline JS it really loads. Theme-agnostic: works by parsing the rendered HTML rather than relying on theme.json, so it reflects what a browser truly receives (colors resolved by PHP at runtime, page-builder output, etc). Calls the site-local wp-mcp-bridge/v1 REST route.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path of the page to inspect, e.g. "/" or "/about/". Defaults to the homepage. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does well: it discloses the mechanism (parsing rendered HTML, calling the site-local wp-mcp-bridge/v1 REST route) and enumerates the returned payload. It stops short of noting auth/preconditions or the cost/side effects of forcing a page render.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and output are front-loaded in the first sentence, with mechanism and caveats following. It is a single dense paragraph with mild redundancy ('actual rendered HTML', 'really loads', 'what a browser truly receives').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description still enumerates what is returned (theme name, stylesheet/script URLs, inline CSS/JS) and how it is obtained, which is what an agent needs to call and interpret it. Missing only auth/prerequisite and latency caveats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'path' parameter is already documented with an example and its homepage default, so the baseline is 3. The description adds no extra syntax or edge-case detail (trailing slashes, query strings) beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('inspect the actual rendered HTML... return its theme name plus stylesheet URLs, script URLs, inline CSS/JS') and differentiates itself from siblings like get_page/get_asset_content by explaining it parses rendered HTML rather than theme.json. An agent can immediately tell what comes back.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for when this tool is the right choice: when you need what a browser truly receives (runtime-resolved colors, page-builder output) rather than theme.json metadata. However it never names a sibling tool or states an explicit exclusion, so the routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List/search pages on the connected WordPress site via GET /wp-json/wp/v2/pages. Supports search, pagination and status filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number for pagination. | |
| search | No | Free-text search term to filter pages by title/content. | |
| status | No | Page status filter, e.g. "publish", "draft", "any". Defaults to WordPress's default (publish). | |
| per_page | No | Number of results per page (max 100). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It does disclose that this is a GET request, implying a read-only operation, and indicates supported filtering capabilities. But it does not mention authentication needs, default response shape, or WordPress-specific status behavior beyond what the schema already states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, information-dense sentences with no filler. The endpoint is included, the primary action is front-loaded, and the supported capabilities are listed clearly without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with fully documented optional parameters and no output schema, the description plus schema covers endpoint, action, and filters. It could be more complete by noting that get_page should be used for a single page or describing the expected response collection, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters already have meaningful descriptions. The tool description only groups them at a high level ('search, pagination and status filtering') and does not add details beyond what the schema provides, which warrants the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List/search') and a clear resource ('pages on the connected WordPress site'), and adds the exact endpoint. It is clear enough to be distinguished from get_page/create_page/update_page by collection-vs-singular and read-vs-write semantics, though it does not explicitly name a sibling alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied by 'List/search pages' and the mention of search, pagination, and status filtering. However, the description does not explicitly say when to prefer this over get_page for a single page, or when not to use it, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing page via POST /wp-json/wp/v2/pages/. Only the fields provided are sent; omit a field to leave it unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The numeric WordPress page ID to update. | |
| meta | No | Meta fields object to merge/update on the page. | |
| title | No | New page title. | |
| status | No | New publication status. | |
| content | No | New page body as an HTML string. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the operation is a POST (mutation) and explains the partial-update behavior: only provided fields are sent, omitted fields are left unchanged. This is valuable context beyond the schema. However, it does not mention error handling, permissions, or response format, leaving some gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the core action and endpoint, then add a single critical behavioral note. No filler or redundancy. Every word earns its place, making it an exemplar of concise writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with 5 parameters, all documented in the schema, and no output schema, the description covers the essential operation and its update semantics. It does not mention the return value (e.g., the updated page object), but that is not strictly required. It also omits authentication and error details, which are common to WordPress REST API tools. Overall, it is adequate for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – each parameter (id, meta, title, status, content) has its own description in the schema. The tool description adds no per-parameter meaning beyond that; it only states a global behavior (partial update). Therefore, the schema does the heavy lifting, and the description adds minimal extra parameter semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update an existing page' with a specific HTTP method and endpoint. This distinguishes it from siblings like list_pages, get_page, and create_page, which cover list, read, and create operations respectively. The verb 'Update' and resource 'existing page' are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool when you need to modify an existing page, and it notes that omitted fields remain unchanged, which is a key usage rule. However, it does not explicitly mention when not to use it or name alternatives, though the contrast with siblings is implicit. Clear context but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_pageget_asset_contentget_pageget_theme_styleslist_pagesupdate_pageScored across 6 tools
Each tool targets a distinct resource and action: list/get/create/update for pages, and get_theme_styles/get_asset_content for inspecting page-rendered assets. There is no overlap or ambiguity between any of the six tools.
All tool names follow a consistent verb_noun pattern: list_pages, get_page, create_page, update_page, get_theme_styles, get_asset_content. Naming conventions are uniform and predictable.
Six tools is a well-scoped size for this server's purpose, covering page operations and theme asset inspection without redundancy. Each tool earns its place and the set is not too thin or bloated.
The page CRUD covers list, get, create, and update, but notably omits delete_page, which is a significant gap in lifecycle management. The theme style and asset tools cover their niche well, but the missing delete operation prevents full page lifecycle management.
AI-powered design and management for Webflow Sites
Publish to self-hosted WordPress from AI agents: markdown, images, SEO, and Notion sync.
Live-checks whether a WordPress site is ready to be safely operated by AI agents.
AI agent website builder. Create and publish link-in-bio sites via MCP or REST API.
