generoi / gds-mcp
WordPress MCP abilities for content management, translations, and forms
Requires
- php: >=8.2
Requires (Dev)
- laravel/pint: ^1.17
- php-stubs/wp-cli-stubs: ^2.12
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^9.0
- szepeviktor/phpstan-wordpress: ^2.0
- wp-phpunit/wp-phpunit: ^7.0
- yoast/phpunit-polyfills: ^2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-master
- v0.10.1
- v0.10.0
- v0.9.0
- v0.8.3
- v0.8.2
- v0.8.1
- v0.8.0
- v0.7.5
- v0.7.4
- v0.7.3
- v0.7.2
- v0.7.1
- v0.7.0
- v0.6.3
- v0.6.2
- v0.6.1
- v0.6.0
- v0.5.2
- v0.5.1
- v0.5.0
- dev-feat/expose-core-abilities
- dev-fix/audit-medium-low
- dev-fix/audit-high
- dev-docs/oauth-connect-guide
- dev-feat/oauth-server
- dev-ci/satis-rebuild-hook
- dev-fix/resource-uri-compat
- dev-fix/php-errors
- dev-feat/content-replace-ability
- dev-fix/machine-translate-single-post
- dev-fix/v0.5.1-foundation
- dev-fix/v0.5.0-undo-and-list-filters
- dev-wp70-abilities-api
- dev-feat/woocommerce-integration
- dev-feat/blocks-patch-template-id
- dev-feat/gravity-forms-feeds-ability
- dev-fix/gravity-forms-gfapi-migration
- dev-feat/gravity-forms-update
- dev-feat/mail-send-min-tier
- dev-feat/mail-send
- dev-fix/response-enrichment
- dev-nav-menu-items-ability
- dev-feat/media-upload
- dev-feat/ability-integration-tests
- dev-feature/generic-crud
- dev-fix/stdclass-schema-sync
- dev-blocks-get-defaults
This package is auto-updated.
Last update: 2026-11-16 16:55:21 UTC
README
WordPress MCP abilities plugin for content management, translations, and forms. Exposes WordPress functionality as MCP tools that AI assistants (Claude Desktop, etc.) can use to manage content on behalf of editors.
Built on the WordPress MCP Adapter and Abilities API.
Requirements
- PHP >= 8.2
- WordPress >= 7.0
- MCP Adapter, as an active plugin or the
wordpress/mcp-adapterComposer library (required for MCP HTTP/STDIO transport)
Installation
composer require generoi/gds-mcp wp plugin activate gds-mcp
Install the MCP adapter as a WordPress plugin (wp plugin install mcp-adapter --activate) or as the wordpress/mcp-adapter Composer library. gds-mcp does not declare Requires Plugins: mcp-adapter, because WordPress would then refuse to activate it on sites that load the adapter as a library. If the adapter's classes are present but it is not booted, gds-mcp boots it through WP\MCP\Plugin, so host projects do not need a separate adapter MU-plugin. If the adapter is missing, an admin notice says so.
Architecture
CRUD abilities delegate to the WordPress REST API via rest_do_request() — a pure PHP call that works in HTTP, STDIO, and CLI contexts. Input/output schemas are pulled dynamically from REST route registrations. Permissions are handled by the REST API itself.
Custom abilities (duplication, block patching, translations, etc.) handle operations without REST equivalents, returning REST responses where possible for consistency.
Abilities
REST-Delegated CRUD (all show_in_rest post types and taxonomies)
| Abilities | Description |
|---|---|
gds/content-list, -read, -create, -update, -delete |
Any post type, picked with type (its REST base: pages, posts, media, blocks, templates, …). The list returns {posts, total, pages}; create and update take ACF values in fields |
gds/terms-list, -read, -create, -update, -delete |
Any taxonomy, picked with taxonomy (its REST base: categories, tags, menus, …). The list returns {terms, total, pages} |
gds/nav-menu-items-list, -read, -create, -update, -delete, -move, -reorder |
Menu items, with sibling positions handled server-side. Menus themselves are gds/terms-list with taxonomy: menus |
Other REST parameters pass through — use _fields, search, per_page, page, slug, include, orderby, lang, etc.
Custom Abilities (always available)
| Ability | Description |
|---|---|
gds/help |
Grouped summary of all available tools and resources |
gds/posts-duplicate |
Clone a post with content, meta, terms, and featured image |
gds/posts-bulk-update |
Update status or meta across multiple posts (supports dry run) |
gds/revisions-list |
List revisions for a post (REST-delegated) |
gds/revisions-read |
Read a single revision (REST-delegated) |
gds/revisions-restore |
Restore a post to a previous revision |
gds/blocks-get |
Block details with attributes, supports, and real-world usage examples from published posts |
gds/blocks-patch |
Update specific blocks within a post without replacing full content |
Block markup checks
gds/content-create, gds/content-update and gds/blocks-patch check the block markup they write, so markup that saves but renders nothing does not pass as a success.
Refused (the call returns an error and nothing is saved):
- Block names missing from the PHP block registry, with the closest registered name. A name that already appears in saved content passes, since blocks registered only in JavaScript and blocks of inactive plugins are not in the registry.
core/missing, the editor's placeholder for an unregistered block.- Inner blocks or HTML inside
core/block(a synced pattern renders itswp_blockpost and discards them), including ablocks-patchofinner_blocks,inner_htmlor a prepend/append on acore/block. Edit thewp_blockpost itsrefpoints to instead.
Warned about, in a warnings array in the result (present only when there are warnings):
- Attribute keys the block type does not define (block-supports attributes count), and values that fail its type or enum.
- Raw
stylevalues equal to a theme.json preset: colors, gradients, border color, font size and spacing. They are reported, never rewritten, because the preset attributes also change a static block's saved classes. - A
blocks-patchattribute that is saved in the block's HTML but could not be synced there (unsupported selector, or no matching element). Patchinner_htmltoo.
Resources (always available)
| Ability | URI | Description |
|---|---|---|
gds/block-types-list |
blocks://catalog |
All registered block types (REST-delegated to /wp/v2/block-types) |
gds/site-map |
site://pages |
Site structure from navigation menu + disconnected pages |
gds/design-theme-json |
theme://json |
Design tokens from theme.json + resolved CSS custom properties |
ACF (when active)
| Ability | URI | Description |
|---|---|---|
gds/acf-fields |
acf://fields |
ACF field groups with fields, types, and post type assignments |
ACF fields are also included in REST responses for post types via the acf field, so gds/content-read returns them. Write them with the fields input of gds/content-create / gds/content-update.
Polylang (when active)
| Ability | Description |
|---|---|
gds/languages-list |
List languages (REST-delegated to /pll/v1/languages) |
gds/translations-create |
Create a translated post linked via Polylang, keeping author and featured image; optional seo fields |
gds/translations-create-term |
Create a translated taxonomy term |
gds/translations-audit |
Audit content for missing translations |
gds/strings-list |
List Polylang string translations |
gds/strings-update |
Update a string translation |
gds/translations-machine |
Machine-translate via DeepL (Polylang Pro) |
Polylang also adds lang and translations fields to all REST responses automatically.
Gravity Forms (when active, REST API must be enabled)
| Ability | Description |
|---|---|
gds/forms-list |
List forms (REST-delegated to /gf/v2/forms) |
gds/forms-read |
Read a form with fields |
gds/forms-create |
Create a form |
gds/forms-entries |
List form submissions |
Cache (sage-cachetags)
| Ability | Description |
|---|---|
gds/cache-clear |
Flush site cache or purge by tag |
Yoast SEO (when active)
| Ability | Description |
|---|---|
gds/seo-read |
Read a post's or term's SEO title, meta description, focus keyphrase, canonical, robots, cornerstone, breadcrumb title, primary category and social (Open Graph / X) title, description and image — stored values plus what Yoast outputs |
gds/seo-update |
Update any of those fields; empty string or 0 clears a field. Undoable |
Redirects (Safe Redirect Manager / Redirection / Yoast)
| Ability | Description |
|---|---|
gds/redirects-manage |
List or create URL redirects (auto-detects plugin) |
Stream (when active)
| Ability | Description |
|---|---|
gds/activity-query |
Query the activity log |
Connecting
gds-mcp registers WordPress abilities. The wordpress/mcp-adapter plugin exposes those abilities as an MCP server.
STDIO (developers with shell access)
{
"mcpServers": {
"wordpress": {
"command": "ddev",
"args": ["wp", "mcp-adapter", "serve", "--server=mcp-adapter-default-server", "--user=admin"]
}
}
}
OAuth (production, remote access — recommended)
With OAuth enabled, anyone adds the site as a custom connector by URL alone: no application password, no base64, no npx. Each person signs in with their own WordPress account and gets a token carrying their own capabilities. It works in Claude Desktop, claude.ai, mobile and Claude Code.
1. Enable it — the module is off unless the site says otherwise:
// Bedrock config/application.php Config::define('GDS_MCP_OAUTH', env('GDS_MCP_OAUTH') ?? true); // Or plain WordPress, in wp-config.php define('GDS_MCP_OAUTH', true);
2. Check discovery answers — a client that cannot read these never starts:
curl https://example.com/.well-known/oauth-authorization-server curl https://example.com/.well-known/oauth-protected-resource/wp-json/mcp/mcp-adapter-default-server
3. Connect — in Claude, add a custom connector pointing at https://example.com/wp-json/mcp/mcp-adapter-default-server. Claude registers itself, sends the person to wp-login.php if needed, and shows a consent screen. Claude Code takes the same URL:
claude mcp add -s local --transport http my-site https://example.com/wp-json/mcp/mcp-adapter-default-server
Connecting, for the person doing it
Send them this, with the URL filled in. They need nothing from you but a WordPress account on the site.
- In Claude, open Settings → Connectors and choose Add custom connector (in Claude Desktop it's the same screen; on claude.ai it's under your profile menu).
- Paste the site's MCP URL —
https://example.com/wp-json/mcp/mcp-adapter-default-server— give it a name, and click Add. - Claude opens the site in a browser window. Sign in with your normal WordPress account if you are not already, then check the page that appears: it names the application asking, the account you are signed in as, and where it will send you back. Click Allow access.
- That's it — the connector shows as connected, and Claude can read and write whatever your account can, including drafts and private posts.
Two things worth knowing:
- You are connecting as yourself. Claude gets exactly your permissions, no more. If you cannot edit something in wp-admin, Claude cannot either.
- You can disconnect at any time, from either end: remove the connector in Claude, or open Users → MCP connections in wp-admin and click Revoke. Revoking takes effect immediately.
If step 3 says your account is not allowed to connect, ask a site administrator — connecting needs the same permission as editing posts.
Requirements
- HTTPS (localhost and
local/developmentenvironments are exempt) - Pretty permalinks: the authorization, token and registration endpoints are paths under
/mcp-oauth/, and a site with plain permalinks has no rewrite rules to route them /.well-known/must reach WordPress. The common nginx recipe denies every dotted path (location ~ /\. { deny all; }) — see.ddev/nginx/well-known.confin the kaskipuu project for the override. Kinsta passes it through as-is.
Allowed callback hosts
Client registration is open to anyone, and the consent screen shows whatever name a client gave itself. So a client may only register a callback on a host this site allows (plus loopback, which lands on the person's own machine). Others get invalid_redirect_uri naming the refused host. The defaults are the clients known to work:
| Client | Callback host |
|---|---|
| Claude (claude.ai, Desktop, mobile) | claude.ai, claude.com |
| Claude Code, VS Code | loopback; vscode.dev |
| ChatGPT | chatgpt.com |
| Microsoft Copilot Studio | *.consent.azure-apim.net |
| Microsoft 365 Copilot | teams.microsoft.com |
To allow only some of them, or another client, define the list (it replaces the defaults; *.example.com matches subdomains):
Config::define('GDS_MCP_OAUTH_REDIRECT_HOSTS', ['*.consent.azure-apim.net']);
or filter gds-mcp/oauth_redirect_hosts. A host taken off the list stops working for clients already registered on it. The list only stops callbacks to someone else's server: someone with their own account on an allowed platform can still register a connector there, so the consent screen shows the callback host prominently, and people should still check it.
Managing access
- Users → MCP connections lists connected applications and revokes them. Revoking kills that grant's access and refresh tokens immediately. Everyone sees their own; anyone who can manage users sees all.
- Connecting requires
edit_postsby default — filtergds-mcp/oauth_capabilityto change it. The same capability is the MCP endpoint's floor on every site, OAuth or not (it raises the adapter's defaultread; a capability another plugin set is kept). What a token may then do is governed per ability byCapabilityPolicy, exactly as for a cookie session. - Enabling OAuth raises the MCP endpoint's own floor to that same capability, for every client including ones using an application password. The adapter's default is
read, which would otherwise let a subscriber reach the endpoint the consent screen refuses them. - Deactivating the plugin revokes every connection, and uninstalling removes the grants, refresh tokens and client registrations. Deactivation is a real revocation, not a pause.
- Access tokens last an hour, refresh tokens 30 days and rotate on every use. Tokens are stored hashed and are bound to the MCP endpoint they were issued for, so a leaked token is not a general-purpose site credential.
Read-only mode
Define GDS_MCP_READ_ONLY as true (or filter gds-mcp/read_only) to unregister every ability not annotated readonly => true, an ability with no annotation included, whichever plugin registered it. The write tools are then gone from every MCP server, core's /wp-abilities/v1 routes, gds-assistant and gds/help alike; one registered later can't run, and gds-assistant's undo is refused. Only the MCP adapter's own mcp-adapter/* dispatchers stay.
Config::define('GDS_MCP_READ_ONLY', env('GDS_MCP_READ_ONLY') ?? false);
Remote clients: mail and web fetch
gds-assistant asks the person before every gds/mail-send and before gds/web-fetch reaches a host they have not trusted. A remote client has no such step, so a prompt injection in something it reads (a form entry, a fetched page) could have it mail data out, or put data into a URL. For a remote client, meaning an MCP request, an OAuth token or an application password:
gds/mail-sendis refused.gds/web-fetchis refused unless the site lists the hosts it may fetch from. Every redirect hop has to be on the list too. Read-only mode keeps web-fetch, so this matters there as well.
add_filter('gds-mcp/web_fetch_allowed_hosts', fn () => ['example.com', '*.example.com']);
The same list, when set, also applies in gds-assistant.
Gravity Forms feed secrets
gds/feeds-* never return the value of a feed setting Gravity Forms encrypts (an API key or the like). Such a value reads as ********, and the feed's masked array lists its keys. Sent back unchanged to feeds-update, the mask keeps the stored value; feeds-create leaves that setting unset; any other value replaces it. feeds-duplicate copies the real value. Add other secret keys with the gds-mcp/feed_secret_fields filter (fn (array $keys, string $addonSlug) => [...$keys, 'token']).
HTTP with an application password
Still the simplest option for a shared machine-to-machine credential, or where OAuth cannot be enabled.
An application password is not bound to the MCP endpoint the way an OAuth token is: it works on every REST route the account can reach, core's /wp-abilities/v1 routes included. Treat it as a full login for that account, and prefer OAuth for anything a third-party service holds.
1. Create an application password:
# Via WP-CLI wp user application-password create USERNAME yourname-claude-mcp --porcelain # Or via WP Admin: Users > Profile > Application Passwords
2. Claude Code:
AUTH=$(echo -n 'USERNAME:YOUR_APP_PASSWORD' | base64) claude mcp add-json -s local my-site \ "{\"type\":\"http\",\"url\":\"https://example.com/wp-json/mcp/mcp-adapter-default-server\",\"headers\":{\"Authorization\":\"Basic $AUTH\"}}"
3. Claude Desktop:
{
"mcpServers": {
"wordpress": {
"command": "npx",
"args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
"env": {
"WP_API_URL": "https://example.com/wp-json/mcp/mcp-adapter-default-server",
"WP_API_USERNAME": "USERNAME",
"WP_API_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
}
}
}
}
Upgrade notes
- 0.8.2:
gds/posts-bulk-updateset_metavalues are now run through kses for users withoutunfiltered_html, as post content already was. Besides stripping disallowed HTML, kses encodes a bare&as&, so meta that relied on a raw&(URLs with query strings, for example) is stored encoded for those users. - After 0.8.2: web-fetch hosts trusted with "Approve & trust" are kept per user (or site-wide when an administrator trusts them). The old shared list (
gds_mcp_trusted_web_hosts) recorded no owner, so it is deleted on upgrade rather than carried over: each user re-trusts their hosts once. - Unreleased: OAuth clients may only use callbacks on the allowed hosts ("Allowed callback hosts" above); a connection through any other host has to be allowed and made again. Remote clients can no longer send mail, and fetch only from
gds-mcp/web_fetch_allowed_hosts.gds/posts-bulk-updateandgds/translations-audittake only the post types the content-* tools list and no internal statuses. Feed secrets read as********(see "Gravity Forms feed secrets").
Development
composer install composer lint # Check code style composer lint:fix # Fix code style
Testing
npx @wordpress/env start npx @wordpress/env run tests-cli wp plugin activate gds-mcp polylang-pro gravityforms wordpress-seo safe-redirect-manager redirection stream npx @wordpress/env run tests-cli --env-cwd=wp-content/plugins/gds-mcp vendor/bin/phpunit npx @wordpress/env stop
License
MIT