Documentation
Installation
- Upload the plugin zip via Plugins → Add New → Upload Plugin.
- Activate it. A unique 256-bit API key is generated automatically.
- Open Dashboard → MCP to see your key and endpoint.
Connecting a client
The settings screen renders a ready-made config block. Copy it into your MCP client:
{
"mcpServers": {
"my-site": {
"type": "http",
"url": "https://example.com/wp-json/custom-mcp/v1/mcp",
"headers": { "x-custom-mcp-api-key": "your-key-here" }
}
}
}
The key travels in the x-custom-mcp-api-key header and is compared in constant time. Requests without a valid key are rejected with a 401.
Connect your editor
Step-by-step setup guides with the exact config file and shape for each client:
Tool reference
Site and options
wp_get_site_info— name, URL, version, active theme, detected builders, enabled write rootswp_get_option/wp_update_option— read and write any optionwp_get_theme_mods/wp_update_theme_mod— Customizer settingswp_get_custom_css/wp_update_custom_css— the active theme’s custom CSS
Content
wp_get_posts/wp_get_post— list and read any post typewp_get_post_types— every registered post type on the sitewp_create_post/wp_update_post/wp_delete_postwp_get_post_meta/wp_update_post_meta/wp_delete_post_metawp_upload_media/wp_get_media— media library
Taxonomies
wp_get_taxonomies— what a post type supports (category and post_tag for posts, product_cat and product_tag for WooCommerce products)wp_get_terms— existing terms with id, slug, parent and post countwp_set_post_terms— assign terms by name or id, replacing or appending; names that do not exist yet are createdwp_delete_term— remove a term
Page builders
wp_get_builder_data— detect the builder and return the decoded layout, its storage location and encodingwp_update_builder_data— write a layout back, re-encoded the way that builder stores it, running its cache invalidation
Both accept an explicit meta_key, so a builder the plugin has never seen still works.
Filesystem
wp_list_files/wp_read_file/wp_write_file/wp_delete_file— scoped to an enabled rootwp_list_plugins/wp_set_plugin_activewp_list_themes
Roots are plugins, themes, mu-plugins and uploads, each toggled independently in settings. Writes are restricted to php, js, css, json, txt, md, svg, html, htm, xml, csv, po, pot and mo.
Extending
Register a builder the plugin does not know about:
add_filter( 'custom_mcp_builders', function ( $builders ) {
$builders['my-builder'] = array(
'label' => 'My Builder',
'store' => 'meta',
'meta_key' => '_my_builder_data',
'after_save' => 'my_builder_flush_cache',
);
return $builders;
} );
Add your own tools with custom_mcp_tools to advertise them and custom_mcp_execute_tool to handle the call. Return anything non-null to claim it.
Security notes
- Read-only out of the box. Every write root is disabled on a fresh install — the connector cannot create or modify a single file until you switch one on.
- Keys are unique per install and generated on activation — no shared default ships.
- The endpoint fails closed: with no key configured every request is rejected, and both the JSON-RPC and streaming routes require the key.
- The API cannot widen its own access. Write roots, the IP allowlist and the key itself are changeable only in wp-admin, so a leaked key cannot be used to turn on file writing or silently rotate the key.
- Repeated invalid keys from one address are rate-limited; a valid key is never locked out.
- Every write is recorded in an audit log in Dashboard → MCP, with the tool, target and source address, plus last-connection and last-rejected-key times.
- An optional IP allowlist restricts which addresses may call the endpoint. Behind some proxies the server sees a different address, so test before relying on it.
- Enabling a write root lets the MCP place executable PHP on your server. Treat the API key as a server credential and turn write roots off when you are not actively building.