AI code editor, Native OAuth
Cursor WordPress MCP. One click, or one mcp.json entry.
Cursor WordPress MCP setup can be a single click: GoBuildWP's Connect screen offers a Cursor install link that writes the server for you. The same entry can go by hand into ~/.cursor/mcp.json for every project or .cursor/mcp.json for one. Cursor merges the two files, and the project file wins when both define the same name.
Checked against Cursor's documentation on 29 September 2026, entries from GoBuildWP Free 1.18.6
{
"mcpServers": {
"gobuildwp-your-site-com": {
"url": "https://your-site.com/wp-json/mcp/wppilot-oauth"
}
}
}- Config
- ~/.cursor/mcp.json, .cursor/mcp.json
- Remote key
- url (headers for a token)
- Manage in
- Customize, MCPs
Setup
Add WordPress in Cursor's MCP settings
Cursor has moved MCP management into Customize in the sidebar, under MCPs. Older guides that point at a settings page named Tools are out of date.
Use the install link, or choose a file
On GoBuildWP's Connect screen pick OAuth, then Cursor, and press One-click install; Cursor opens and asks to add the server. To do it by hand, paste the block into ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this repository).
Keep secrets out of a committed file
OAuth entries hold no secret, so .cursor/mcp.json is safe to commit. For a token, write the header as Bearer ${env:GOBUILDWP_TOKEN} and export the variable, rather than pasting the token into the repository.
Sign in
Open Customize, then MCPs. The new server asks for authentication; start it and approve the WordPress login in the browser. Cursor's CLI does the same with agent mcp login and the server name.
Switch off the tools you do not need
In the chat tools list, clicking a tool name toggles it. A coding session rarely needs WordPress user or plugin management, so leaving those off keeps the model's choices short.
Decide the run mode
Cursor asks before using MCP tools by default. Under Cursor Settings, Agents, Approvals & Execution you can choose Auto-review, Allowlist or Run Everything; Allowlist with only read abilities listed is a good start.
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 Cursor. 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.
Connect screen
The Cursor entries GoBuildWP writes
For OAuth GoBuildWP writes the shortest entry any client gets: mcpServers, the server name and url, nothing else. Beside it sits a One-click install button, a cursor:// install link whose config parameter is that same object in base64. The token entry adds type http and an Authorization header; the Application Password entry starts the npx bridge. When Cursor is open on the machine that hosts WordPress, a fourth entry needs no credential: a command server that runs wp wppilot mcp serve.
| OAuth 2.1 | The url-only entry or the install link. Cursor signs in through a loopback callback on port 8787 of your machine. |
|---|---|
| Access token | url plus headers. Cursor expands ${env:NAME} in headers, so the token can stay in your shell. |
| Application Password | A stdio entry running @automattic/mcp-wordpress-remote through npx, with the credentials in env. |
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.
{
"mcpServers": {
"gobuildwp-local": {
"command": "wp",
"args": [
"--path=/var/www/html",
"wppilot",
"mcp",
"serve",
"--user=your-wp-user"
]
}
}
}{
"mcpServers": {
"gobuildwp-your-site-com": {
"type": "http",
"url": "https://your-site.com/wp-json/mcp/wppilot",
"headers": {
"Authorization": "Bearer wpp_YOUR-ACCESS-TOKEN"
}
}
}
}Inside Cursor
Where Cursor shows MCP state and errors
The MCPs screen under Customize lists each server with a switch and its tools. When a server will not start or sign in, open the Output panel (Ctrl+Shift+U on Windows and Linux) and choose MCP Logs from the dropdown; the HTTP status from WordPress, or the npx bridge's error, is printed there.
Cursor's documentation gives no restart button for a single server; removing it and adding it again is the documented reset, and toggling it off and on in MCPs usually reconnects. From the terminal, agent mcp list shows configured servers and agent mcp list-tools with a server name shows what it exposed.
Approvals can be written down rather than clicked: a permissions.json in ~/.cursor or the workspace's .cursor folder accepts an mcpAllowlist of server:tool entries. List the WordPress read abilities there and every write keeps asking. Team plans can also restrict which MCP servers members may add, under Team Settings.
Signs it worked
- The server shows as enabled in Customize, MCPs
- MCP Logs shows a successful connection, no 401
- The chat tools list includes wppilot/ abilities
- A write asks for approval, then the site refuses it on Read Only
Troubleshooting
Cursor errors and their causes
| Symptom | Cause and fix |
|---|---|
| The install link opens Cursor but nothing is added | Cursor needs to be running and signed in when the link is followed. Open it first, then press One-click install again, or paste the block into mcp.json. |
| The server sits waiting for authentication | Sign-in has not been completed. Start it from Customize, MCPs, and allow the browser to reach the loopback callback on port 8787; a local firewall blocking that port stops the flow. |
| MCP Logs shows 401 for a token entry | The header value is wrong, the token expired, or ${env:…} did not resolve because Cursor was started before the variable existed. Restart Cursor from a shell that has it. |
| The project entry is ignored | A server with the same name in the project file overrides the global one. Check both files for duplicates, and remember the project file only loads in that folder. |
| npx bridge errors on the Application Password route | Check Node.js on the PATH Cursor sees, the endpoint, credential revocation and the returned authentication error; password spacing alone is not a diagnosis. Prefer OAuth in Cursor; it needs neither. |
First task
A first prompt for a theme or plugin repository
Cursor is usually open on code, so ask it to relate the code to what the site really renders. It reads; it does not edit either side.
Use the WordPress MCP server. Do not edit files
or the site.
1. wppilot/list-extensions: which theme is active?
2. wppilot/get-page-view-link for the front page.
3. wppilot/verify-rendered-page on that URL: headings
and landmarks as a visitor gets them.
4. Point to the template files in this repo that
produce each heading you found.After Cursor can see the site
Theme fix in Cursor, proof on the staging site
Once the read-only prompt has tied headings to template files, the useful loop in Cursor is to edit the theme in the repository, deploy to staging, and ask the agent to check the result through WordPress rather than through the code alone. Keep the Allowlist limited to reads such as wppilot/verify-rendered-page, wppilot/audit-accessibility and wppilot/check-contrast, so Cursor runs the checks without stopping and every write still asks.
When a fix needs content rather than code, for example a heading that lives in a page and not in a template, let Cursor propose it with wppilot/preview-ability first, where GoBuildWP can project the change. The preview stores a proposal and returns a diff and a wp-admin link where a person can apply or discard it; the page itself is not touched until then. wppilot/apply-preview refuses if the fields shown in the diff, or the values the projection read, changed in the meantime; an unrelated edit elsewhere on the page does not block it.
One project file per site, or the Cloud link
A committed .cursor/mcp.json with one OAuth entry is the cleanest setup for a repository that belongs to one site. For an agency whose themes ship to many sites, GoBuildWP Cloud is an option: Cursor is on its list of apps that sign in once with OAuth, the Cloud link goes into ~/.cursor/mcp.json as a single url entry, and you choose which connected sites Cursor may reach. Each call still runs on the target site under its safety profile; a site on localhost stays a direct or WP-CLI connection, because Cloud reaches sites over the internet.
FAQ
Cursor questions
Does Cursor support OAuth for a WordPress MCP server?
Yes. A url-only entry triggers Cursor's sign-in, which returns to a loopback address on your machine. Cursor also accepts a fixed OAuth client in an auth object, which GoBuildWP does not need.
Is there a limit on how many WordPress tools Cursor can use?
Cursor's documentation does not state one, and Cursor describes loading MCP tools on demand. Turning off abilities you do not use still keeps the model's choices clearer.
Can I share the Cursor WordPress configuration with my team?
Commit .cursor/mcp.json with the OAuth entry. Each teammate signs in as their own WordPress user, so the site's audit trail names the person, not a shared account.
Does Cursor's CLI use the same servers?
Yes. The agent command reads the same configuration and adds agent mcp list, list-tools and login for use outside the editor.
Can Cursor start GoBuildWP itself on a local WordPress install?
Yes, if WordPress and WP-CLI run where Cursor runs. Expand Local connection over WP-CLI on the Connect screen and copy its mcp.json block into .cursor/mcp.json: a gobuildwp-local server whose command is wp, with --path pointing at the site's directory and --user naming the WordPress login it acts as. Cursor launches that process and talks stdio to it, so there is no password, token or sign-in, and every call still runs the same abilities, safety profile, confirmations and permission checks as HTTP. Behind Docker, prefix the command with docker exec -i and the container; for a site on another server, use the url entries instead.
Related
Other editors with a JSON config
- VS Code: the servers key instead of mcpServers, and a trust prompt
- Devin Desktop (Windsurf): serverUrl in mcp_config.json
- Zed: context_servers in settings.json
- Audit WordPress security with AI: worked example
Cursor documentation read on 29 September 2026
Install the WordPress server in Cursor with one click.
Sign in as your own WordPress user, allowlist the reads, and let the first prompt compare code with the rendered page.