Terminal agent, Native OAuth
Claude Code WordPress MCP. One command, three scopes.
For Claude Code WordPress MCP, install Claude Code and GoBuildWP first. Public HTTP reaches the site from Claude Code's execution environment; same-host WP-CLI and local OAuth or bridge routes have separate runtime and network prerequisites. One claude mcp add command registers the site; /mcp inside a session runs the browser sign-in and shows whether the server is connected, pending approval or failing.
Checked against Claude Code's documentation on 29 September 2026, entries from GoBuildWP Free 1.18.6
claude mcp add gobuildwp-your-site-com --transport http https://your-site.com/wp-json/mcp/wppilot-oauth- Add with
- claude mcp add --transport http
- Stored in
- ~/.claude.json, or .mcp.json for a project
- Status and sign-in
- /mcp
Setup
Add a WordPress site to Claude Code
Pick the scope before you run the command. It decides who else gets the server and whether the credential ends up in a repository.
Choose a scope
local, the default, keeps the server in ~/.claude.json for the current project only. user makes it available in every project. project writes .mcp.json at the repository root for the whole team, which suits OAuth because nothing secret is stored.
Run the generated command
Copy it from Connect, OAuth, Claude Code. Server names may contain only letters, numbers, hyphens and underscores, which the suggested gobuildwp-your-site-com already satisfies.
Sign in from /mcp
Start claude, type /mcp, pick the server marked Needs authentication and authenticate. The browser opens your WordPress login; approve as the WordPress user this terminal should act as.
Approve a shared .mcp.json once
A project-scoped server shows Pending approval the first time a teammate opens the repo interactively. That prompt is Claude Code's, separate from anything GoBuildWP asks.
Write permission rules if you script it
Claude Code's permission rules name an MCP tool as mcp, the server name and the tool name, joined by double underscores, so you can allow the read tools and leave everything else asking.
Working in a shell on the web server?
Skip the credential entirely. Open Connect, expand Local connection over WP-CLI, and copy its claude mcp add line: it ends in wp --path=<the site's directory> wppilot mcp serve --user=<your login>, filled in for that install. Claude Code then starts WP-CLI itself, as the WordPress user --user names.
Verify the connection before allowing changes
Select Read Only explicitly; the default is Production Safe. Use a dedicated identity with manage_options on a single site, or superadmin on multisite. Match the named tool call, site URL and returned record ID against WordPress.
Use the gobuildwp-your-site-com MCP server in Claude Code. Do not change anything.
1. Report the active GoBuildWP safety profile.
2. List the abilities this connection can see.
3. Call wppilot/get-site-settings and report the site URL and locale.
4. Call wppilot/list-content for the five newest pages,
then wppilot/get-content on one of them.
5. Name every ability you called and each WordPress ID you read.These setup instructions are not a recorded live-client test. Keep credentials out of repositories, logs and shared files.
Inside Claude Code
Reading /mcp and claude mcp get
/mcp lists each server with one of a handful of states: Connected, Needs authentication, Failed to connect, Pending approval, or Disabled for this project. From the same screen you can reconnect, disable a server or clear its stored authentication, which is the quickest way to switch the WordPress user an OAuth connection signs in as.
Outside a session, claude mcp list prints every server, and claude mcp get with the server name shows its configuration. Recent releases add an Issue line to that output carrying the HTTP status, which tells a 401 from the site apart from a DNS or TLS failure without opening a log.
A server you gave an Authorization header, token or Application Password, is never flagged Needs authentication. A good credential shows Connected; when the site answers 401 or 403 to the header, /mcp reports the server as failed and the detail carries the HTTP status. For a 401, inspect the returned body, credential and expiry, Authorization forwarding, canonical endpoint and server policy. A 403 is an authority or policy clue; transport failures and pending trust are separate.
Signs it worked
- /mcp shows the server as Connected
- claude mcp get shows no Issue line
- Claude Code appears under AI clients on GoBuildWP's home screen, active moments ago
- A write is refused while the profile is Read Only
Connect screen
The Claude Code entries GoBuildWP writes
On a public site Claude Code never goes through npx. The OAuth command registers the OAuth endpoint and leaves sign-in to /mcp. The token and Application Password commands register the canonical endpoint with an Authorization header and --scope user, so the site follows you into every project rather than the one you happened to be in. A collapsed panel under the three steps adds a fourth route for a terminal on the web server itself: claude mcp add with -- and a wp wppilot mcp serve command, so Claude Code launches WP-CLI and speaks MCP over stdio.
| OAuth 2.1 | claude mcp add with the OAuth URL, then /mcp to sign in. Claude Code identifies itself with a Client ID Metadata Document, which GoBuildWP's discovery document advertises support for. |
|---|---|
| Access token | The same command with --header 'Authorization: Bearer …' and --scope user. No sign-in step: /mcp shows it connected, or failed with the HTTP status. |
| Application Password | Direct HTTP with a Basic header built from username:password in base64. Claude Code's health check is then a real authenticated request, so a wrong password fails loudly instead of showing Connected. |
Endpoints on your site: /wp-json/mcp/wppilot-oauth for OAuth, /wp-json/mcp/wppilot for tokens and passwords. Through the optional GoBuildWP Cloud instead, every client uses https://app.gobuildwp.com/mcp with the server name gobuildwp, and a personal Cloud token is read from GOBUILDWP_TOKEN where the client supports environment variables.
claude mcp add gobuildwp-local -- wp --path=/var/www/html wppilot mcp serve --user=your-wp-userclaude mcp add --transport http 'gobuildwp-your-site-com' 'https://your-site.com/wp-json/mcp/wppilot' \
--header 'Authorization: Bearer wpp_YOUR-ACCESS-TOKEN' \
--scope userFirst task
A first task that uses the repository as well as the site
Claude Code's advantage is that it can read your theme or plugin code and the live site in one conversation. This task compares the two and changes neither.
Read-only task. Do not edit files or the site.
1. Call wppilot/agent-context and tell me the safety
profile and my WordPress role.
2. Call wppilot/list-extensions. Find the active theme
and its version.
3. If this repository contains that theme or a child
theme, compare its version header with the site's.
4. Call wppilot/get-page-snapshot on the front page and
list the templates or blocks the repo would affect.Troubleshooting
Claude Code errors and their causes
| Symptom | Cause and fix |
|---|---|
| Failed to connect right after adding a token | Run claude mcp get with the server name and read the Issue line. Check the returned body, credential expiry or revocation, Authorization forwarding, canonical endpoint and server policy. A 403 can indicate authority or policy; diagnose transport and trust failures separately. |
| A teammate sees Pending approval and no tools | The server came from a shared .mcp.json. They approve it once in /mcp. claude mcp reset-project-choices clears an earlier refusal. |
| Large results are cut off | Claude Code caps MCP output at 25,000 tokens by default and warns at 10,000. Ask for narrower reads (a page of list-content rather than everything), or raise MAX_MCP_OUTPUT_TOKENS. |
| ${GOBUILDWP_TOKEN} in .mcp.json arrives empty | Expansion works in url and headers, but only for variables present when Claude Code starts. Export it in the shell first; some credential-named variables are deliberately read as empty. |
| Signed in as the wrong WordPress user | Open /mcp, clear authentication for the server and sign in again. Each OAuth grant is also listed under Connected Apps in WordPress and can be revoked there. |
FAQ
Claude Code questions
Does Claude Code need Node.js or mcp-remote for WordPress?
No. It speaks Streamable HTTP to the endpoint directly for OAuth, tokens and Application Passwords. Node only comes in on a site the Connect screen sees as local, where its OAuth command runs the sign-in through npx mcp-remote instead.
Which scope should a WordPress connection use?
user for a personal token or Application Password, so the secret stays in your home directory. project only for OAuth, because .mcp.json is committed and OAuth stores no secret in it.
Can I automate Claude Code against WordPress in CI?
Yes, with an access token in an environment variable referenced from the configuration. Project servers load without the approval prompt in non-interactive runs, so pair that with a token limited to the abilities the job uses. If the job runs where WordPress and WP-CLI are installed, the stdio route needs no token at all.
Can Claude Code run GoBuildWP through WP-CLI instead of HTTP?
Yes, when Claude Code runs on the same machine or in the same container as WordPress. claude mcp add gobuildwp-local -- wp --path=… wppilot mcp serve --user=… starts the same MCP server the HTTP endpoint serves, with the same abilities, safety profile, confirmations and permission checks, run as that WordPress user. It cannot reach a remote site; wp has to be on Claude Code's PATH, and a site in Docker needs docker exec -i <container> in front of wp. Restart Claude Code after switching abilities on or off, because one process serves the whole session.
Is Claude Code different from Claude Desktop for WordPress?
Yes. Claude Code connects from your machine, so it reaches a local or firewalled site. Desktop's custom connectors connect from Anthropic's cloud and need a public HTTPS site.
Related
The other ways into Claude
- Claude Desktop: connectors from Anthropic's cloud, or a local bundle for sites the cloud cannot reach
- Claude on the web: the browser connector and the Team and Enterprise owner flow
- Codex CLI: OpenAI's terminal agent, configured in TOML
- WordPress MCP for developers: register your own abilities and test an allowed and a refused call from the terminal
- Translate a WordPress site with AI: worked example
- Scheduled WordPress audits: worked example
Claude Code documentation read on 29 September 2026
Let Claude Code read the site before it edits the repo.
Add the server at user scope, sign in once, and keep the profile read-only until the first comparison comes back right.