Install
This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.
Install straight from GitHub with WP-CLI:
wp plugin install https://github.com/edwinludik-ai/wp-mcp-adapter-server/archive/refs/heads/main.zipA WordPress plugin for the WordPress MCP Adapter that puts an MCP server behind hashed, revocable API keys, each with an optional IPv4/IPv6 allowlist.
It implements the adapter's getting-started steps:
- Step 2: registers the
mcp-keys/get-site-infoability. - Step 3: creates a custom MCP server at
/wp-json/mcp-keys/mcpthat exposes only that ability.
The adapter's default server (/wp-json/mcp/mcp-adapter-default-server) is untouched. The get-site-info ability is not marked public, so it is not exposed there.
Requirements
WordPress 6.9+, PHP 7.4+, and the MCP Adapter plugin active.
Install
Download mcp-api-keys.zip from the latest release and upload it under Plugins > Add New Plugin > Upload Plugin (or wp plugin install mcp-api-keys.zip --activate). Install and activate the MCP Adapter first; this plugin declares it as a required plugin. Deleting the plugin from wp-admin also deletes the stored key hashes.
Use
- Install and activate this plugin (and MCP Adapter).
- Go to Settings > MCP API Keys, enter a label, pick the user the key acts as (use the lowest role that does the job), optionally list allowed IPs, and click Create key.
- Copy the key. It is shown once and only a hash is stored.
- Point your client at the endpoint shown on that page and send the key as
Authorization: Bearer <key>orX-API-Key: <key>:
claude mcp add --transport http my-site https://example.com/wp-json/mcp-keys/mcp \
--header "Authorization: Bearer mcpk_xxxxxxxx_..."
Revoke a key on the same page; it stops working immediately.
Allowed IPs
One rule per line (or comma-separated): an IPv4 or IPv6 address, optionally with a /prefix (203.0.113.7, 198.51.100.0/24, 2001:db8::/32). Leave empty to allow any IP. A key with rules rejects every other address with a 403.
The address checked is the connection's REMOTE_ADDR; X-Forwarded-For and similar headers are ignored (they can be spoofed). Behind a proxy or CDN, REMOTE_ADDR is the proxy, so an allowlist will not do what you want there.
Behaviour
Request to /wp-json/mcp-keys/mcp |
Result |
|---|---|
| valid key, allowed IP | acts as the key's user |
| no key (including cookie or Application Password auth) | 401 |
| unknown id or wrong secret | 401 |
| valid key, IP not allowed | 403 |
| key's user deleted or removed from the site | the user's keys are revoked (401) |
| plain HTTP on a non-local site | 403 mcpk_https; keys cannot be created either |
Keys are secrets in a request header, so they are only accepted (and created) over HTTPS, as WordPress does for Application Passwords. Local environments are exempt. If your site is behind a proxy that terminates HTTPS and WordPress cannot see it, return false from the mcp_keys_require_https filter. If another plugin's rest_authentication_errors filter (for example a firewall) runs before this one and refuses a request, that refusal stands.
Web chat connectors (claude.ai, ChatGPT) sign in with OAuth and cannot use API keys; use a desktop or CLI client.
Development
php tests/check.php # key hashing, header parsing, IP/CIDR matching (no WordPress needed)
bin/build-zip.sh # builds dist/mcp-api-keys.zip, the installable plugin (also what goes to WordPress.org)
End-to-end check against a real WordPress (Playground, with the adapter preinstalled by the blueprint). In one terminal:
npx @wp-playground/cli@latest server --blueprint=tests/blueprint.json --auto-mount --login --port=9400
and in another, once it prints Ready!:
python3 tests/smoke.py
CI and releases
.github/workflows/ci.yml runs on pushes to main, pull requests and tags:
- test: lint plus
tests/check.phpon PHP 7.4, 8.1, 8.3 and 8.4. - standards: PHPCS with the WordPress-Extra and PHP-compatibility rulesets (
.phpcs.xml.dist), roughly what the WordPress.org plugin review looks for. - build:
bin/build-zip.sh, uploadingmcp-api-keys.zipas a workflow artifact. It fails if the plugin headerVersion:and theStable tag:inreadme.txtdiffer. - smoke: unpacks that zip into a real WordPress with the MCP Adapter and runs
tests/smoke.pyagainst it, so the packaged files are what gets tested. - release: on a
v*tag, after the above pass, creates a GitHub release with the zip attached. The tag must match the plugin header'sVersion:(tagv1.0.1needsVersion: 1.0.1). - wporg: on the same tag, commits that zip's files to the WordPress.org SVN repository. Off by default; see below.
To cut a release: bump Version: in mcp-api-keys.php and Stable tag: in readme.txt, add a changelog entry, merge, then git tag v1.0.1 && git push origin v1.0.1.
Publishing to WordPress.org
- Fill in
readme.txt: replaceREPLACE_WITH_WPORG_USERNAMEafterContributors:with your WordPress.org username (thewporgjob refuses to run while it is still there). - Submit the first version by hand: sign in at wordpress.org/plugins/developers/add and upload
mcp-api-keys.zipfrom the GitHub release. The plugin review team reads it, usually within days to a couple of weeks, and emails you. Fix anything they raise and reply. - After approval you get an SVN repository at
plugins.svn.wordpress.org/mcp-api-keys. Whoever can push av*tag can trigger a deploy, so lock it down in this GitHub repo:- Settings > Environments > New environment
wordpress-org, with a required reviewer. Add the secretsSVN_USERNAMEandSVN_PASSWORD(your WordPress.org login, or an SVN password if you set one) to that environment, not to the repository. Each deploy then waits for approval before the secrets are released. - Settings > Secrets and variables > Actions > Variables: add
WPORG_DEPLOY=true. - Settings > Rules: protect the
v*tags so only maintainers can create them, and require passing CI onmain. - Turn on two-factor authentication on your WordPress.org account.
- Settings > Environments > New environment
- Release by pushing a
v*tag as above. Thewporgjob commits the same files the smoke test ran totrunkand tags that version. WordPress.org shows whateverStable tag:inreadme.txtnames.
Banner and icon images are optional; if you add them, put them in .wordpress-org/ and pass ASSETS_DIR to the deploy step.