Connect Amazon Q Developer to your own WordPress site over the Model Context Protocol. Amazon Q talks to your site directly — there is no relay in between, no account to create, and your credentials never leave your machine. The same configuration works in the IDE extensions and in the command line. Setup takes about a minute once MCP Manager is installed.
Free plugin · No account · Runs on your own server · Any WordPress host
Config file
~/.aws/amazonq/mcp.json
Top-level key
mcpServers
Scope
Global, or .amazonq/mcp.json per project
Before you start
You need AcrossAI MCP Manager installed and active on the WordPress site you want Amazon Q to reach, plus an administrator account on that site. If you have not installed it yet, follow the Get Started guide first — it takes about a minute, and the MCP server ships bundled with the plugin.
You also need Node.js available on the machine running Amazon Q, because the connection runs through an npx bridge. Nothing is installed permanently — npx fetches the bridge on demand. Amazon Q Developer runs both as an IDE extension and as a command-line client, and both read the same MCP configuration files, so you only configure this once per machine.
How to connect Amazon Q Developer to WordPress
Step 1
Open Quick Connect and choose Amazon Q Developer
In wp-admin go to AcrossAI → MCP, open the server you want to expose, and start Quick Connect. Pick Amazon Q Developer from the client list. Everything below is generated for you with your real site URL and username already filled in — the snippets here are only so you know what to expect.
Step 2
Generate an Application Password
Click Generate password in the wizard. This creates a standard WordPress Application Password — not your login password — scoped to this connection and revocable at any time from your user profile.
The password is shown once, at creation. Copy it whole, including the spaces — WordPress accepts them. If you lose it, generate a new one rather than trying to recover it.
Step 3
Choose a scope and paste the config
Amazon Q Developer reads MCP servers from two places, and you need to decide which one this site belongs in:
- Global —
~/.aws/amazonq/mcp.json. The server is available in every workspace you open and in the command line. Use this for the site you maintain from wherever you happen to be working. - Per project —
.amazonq/mcp.jsonin the root of one project. The server is available only while Amazon Q is working in that project. Use this when the WordPress site belongs to a specific repository, such as the theme or plugin you build for it.
Copy the JSON from the wizard, open the file you chose — create it if it does not exist — and paste the entry under the mcpServers key. If you already have other MCP servers configured, add this one alongside them rather than replacing the file. The generated config looks like this, with your own values in place of the placeholders:
{
"mcpServers": {
"your-site-mcp-adapter-default-server": {
"command": "npx",
"args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
"env": {
"WP_API_URL": "https://example.com/wp-json/acrossai/mcp",
"WP_API_USERNAME": "your-wp-username",
"WP_API_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
}
}
}
}A project file usually ends up in version control, so prefer the global file when the entry carries an Application Password. If you configure both scopes, give the two entries different server names — two servers sharing one name is ambiguous and awkward to debug.
Step 4
Restart Amazon Q and check the tools
Restart Amazon Q so it reads the new configuration — in an IDE that means reloading the extension or restarting the editor, and on the command line it means starting a fresh session. Your site should appear as an MCP server, and the toolsets it exposes become available in chat. Ask something harmless to confirm it is live — “Which plugins on this site need updating?” is a good first test.
If you used the per-project file, open Amazon Q from inside that project. A project-scoped server is invisible from anywhere else, which is the point of it.
What Amazon Q Developer can do once it is connected
With Abilities Manager installed alongside it, Amazon Q Developer reaches 350+ abilities across 14 toolsets — rising past 800 once it detects the plugins you already run. From inside your editor or your terminal, without switching to a browser tab, it can:
- Read and edit content — posts, pages and any custom post type with their meta and revisions, and surgically edit a page’s block tree without rewriting the page.
- Debug a broken site — read the debug log with secrets redacted, check Site Health, list recent fatal errors and un-pause what WordPress auto-disabled.
- Inspect the database — schema and table sizes, index health, bloated autoloaded options, or
EXPLAINon a slow query. - Manage plugins, themes and core — search WordPress.org, install, update, roll back, and verify files against official checksums.
- Work with files — inside an allowlist you define, with a dangerous-extension blocklist and optional pre-image backups of everything it touches.
- Reach the plugins you already run — WooCommerce, Elementor, ACF, Rank Math, Yoast, WPCode and more, each registering only when that plugin is active.
Every ability runs WordPress’s own capability check for the calling user, so Amazon Q can never do anything your account could not already do. See the full platform overview for the complete catalogue.
Frequently asked questions
Is connecting Amazon Q Developer to WordPress free?
Yes. AcrossAI MCP Manager and Abilities Manager are both free and GPL on WordPress.org, and there is no AcrossAI account to create. You use the Amazon Q Developer access you already have — AcrossAI never charges for AI inference, because none of it runs here.
Does my site data pass through AcrossAI servers?
No. Amazon Q connects straight to your own domain and every request terminates at your /wp-json/ route. There is no relay, no gateway and no telemetry. Whatever Amazon Q reads is still processed by its own provider, so treat it as you would any other prompt.
Does it work on any WordPress host?
Yes, provided you can reach wp-admin. Shared hosting, VPS and managed WordPress all work, because everything runs inside your own install. MCP Manager needs WordPress 7.0 or later and PHP 8.1 or later; Abilities Manager needs WordPress 6.9 or later.
Should I use the global file or a project file?
Use ~/.aws/amazonq/mcp.json when you want the site reachable from every workspace and from the command line — that suits the site you administer day to day. Use .amazonq/mcp.json in a project when the connection only makes sense inside that repository, for instance the theme or plugin you build for that one site. A project file is also the honest place to put a staging site, so it cannot follow you into unrelated work.
Can Amazon Q Developer break my site?
Every ability runs WordPress’s own capability check for the calling user, so Amazon Q can never exceed what your account can already do. Higher-risk operations refuse to run without an explicit confirmation flag, file access is confined to an allowlist you define, search-and-replace is a dry run by default, and any ability can be disallowed site-wide.
Troubleshooting
The file is in ~/.aws/ and Amazon Q ignores it
This is the most common mistake. ~/.aws/ is the shared AWS configuration directory and holds files such as config and credentials that have nothing to do with MCP. The MCP file belongs one level deeper, in the amazonq subfolder: ~/.aws/amazonq/mcp.json. Create the subfolder if it is not there. A file saved as ~/.aws/mcp.json is read by nothing and reports no error.
It works in one project but not in another
Then the entry is in a project file, not the global one. .amazonq/mcp.json applies only while Amazon Q is working inside that project — open a different folder, or run the command line from your home directory, and the server is simply not there. Move the entry to ~/.aws/amazonq/mcp.json if you want it everywhere. Note that a project file has to sit in the root of the project Amazon Q has open: putting it in a subdirectory of a monorepo will not be found from the top level.
Amazon Q does not list the server at all
Amazon Q reads its MCP configuration when it starts, so restart it after every edit — in an IDE, reload the extension or restart the editor; on the command line, start a new session. Check the file is valid JSON: a trailing comma or a missing brace makes the whole file unusable. Confirm your entry sits under mcpServers and not at the root.
The server appears but has no tools
That is the connection working and the catalogue being empty. Either Abilities Manager is not installed — MCP Manager will serve an empty catalogue quite happily — or the abilities exist but are not exposed to this particular server. Open AcrossAI → MCP, select the server, and check its Tools and Abilities tabs. After changing what a server exposes, restart Amazon Q: MCP clients receive their tool list once, at connection time.
Authentication fails, or it worked yesterday and stopped today
Application Passwords are shown once and are not your login password. Generate a fresh one from Quick Connect rather than retyping an old one, and copy it complete with spaces. If the request is being refused rather than failing, check the server’s access rules — a new server requires manage_options until you add a rule, and the gate fails closed. Access is re-checked on every request, so a change to your role or a revoked password takes effect immediately, however long the config has been sitting on disk.
npx is not found
The bridge runs through npx, which ships with Node.js. Install Node.js on the machine running Amazon Q and restart it. If Node is installed through a version manager, an IDE extension may not inherit your shell’s PATH even when the command line works — in that case point command at the absolute path to npx.
Connect a different AI client
The same server works with every MCP client — only the config file and top-level key change. See the guides for Claude Desktop, Claude Code, Cursor, VS Code, GitHub Copilot, Windsurf, Zed, Codex and every other client.
Not installed yet?
Install MCP Manager on your site, then come back and run Quick Connect.