WPTerminal documentation
Let Claude, ChatGPT, Codex, Cursor and other AI assistants manage your WordPress sites, with an approval step before anything risky happens.
Get started
Quickstart
About five minutes. You need a WordPress 6.9+ site on HTTPS and an account there that can write posts. WP-CLI, plugin and theme tools also need an administrator to allow administrative tools.
- 01 / Install
Install the plugin
Download the connector and upload it in wp-admin → Plugins → Add New → Upload Plugin. Activate it.
Download Cmdlane Agent Link (.zip) - 02 / Pair
Connect your site
In wp-admin open Agent Link → Connection (Settings → Agent Link on plugin 1.0) and click Connect to WPTerminal. Sign in to WPTerminal, then approve “WPTerminal” on WordPress’s own Authorize Application screen. No user is created: agents act with your WordPress permissions, limited to content unless an administrator turns on Allow administrative tools (WP-CLI, plugins, themes, users).
- 03 / Connect
Connect your AI
Add the MCP server URL to your assistant and sign in. Then try: “List my WordPress sites.”
Pick your assistant
Step 3
Connect your AI
Every assistant uses the same server URL. Clients that support sign-in open a WPTerminal consent screen; nothing to copy or store. You can see and disconnect agents in Settings → AI Agents.
MCP server URL
Claude
Sign inDesktop app, web and mobile. Added once as a custom connector, signs in with your WPTerminal account.
Claude
Sign inDesktop app, web and mobile. Added once as a custom connector, signs in with your WPTerminal account.
- Open Claude and go to Settings → Connectors.
- Click “Add custom connector”, name it WPTerminal and paste https://wpterminal.com/api/mcp.
- Click Add, then Connect. Approve the WPTerminal consent screen that opens.
- In a chat, enable WPTerminal from the + menu → Connectors.
On Team and Enterprise plans an owner adds the connector under Organization settings; members then click Connect. Free plans allow one custom connector.
ChatGPT
Sign inAdded as a Developer Mode app with OAuth.
ChatGPT
Sign inAdded as a Developer Mode app with OAuth.
- Go to Settings → Apps & Connectors → Advanced settings and turn on Developer Mode.
- Back in Apps & Connectors, click Create. Name it WPTerminal and paste https://wpterminal.com/api/mcp.
- Choose OAuth as the authentication, then Scan Tools and approve the WPTerminal consent screen.
- Click Create. In a new chat, pick WPTerminal from the + menu → More.
Write actions in Developer Mode apps depend on your ChatGPT plan; some plans allow read-only tools only. Workspace admins may need to enable Developer Mode first.
Codex
Sign inOpenAI Codex CLI and IDE extension.
Codex
Sign inOpenAI Codex CLI and IDE extension.
- Add the server, then sign in. A browser window opens for the WPTerminal consent screen.
- After you click Allow, the browser shows Codex's local confirmation page and Codex lists the WPTerminal tools.
codex mcp add wpterminal --url https://wpterminal.com/api/mcp codex mcp login wpterminal
Cursor
Sign inRemote server in mcp.json; Cursor handles the sign-in.
Cursor
Sign inRemote server in mcp.json; Cursor handles the sign-in.
- Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
- Open Cursor Settings → MCP. Next to WPTerminal, click the sign-in prompt and approve the consent screen.
{
"mcpServers": {
"wpterminal": {
"url": "https://wpterminal.com/api/mcp"
}
}
}VS Code
Sign inGitHub Copilot agent mode with an HTTP MCP server.
VS Code
Sign inGitHub Copilot agent mode with an HTTP MCP server.
- Create .vscode/mcp.json in your workspace (or run “MCP: Add Server” from the Command Palette and choose HTTP).
- Start the server from the mcp.json editor. VS Code opens the WPTerminal sign-in in your browser.
{
"servers": {
"wpterminal": {
"type": "http",
"url": "https://wpterminal.com/api/mcp"
}
}
}Windsurf
Sign inRemote server in Windsurf's MCP config.
Windsurf
Sign inRemote server in Windsurf's MCP config.
- Add the server to ~/.codeium/windsurf/mcp_config.json (on Windows, %USERPROFILE%\.codeium\windsurf\mcp_config.json).
- Refresh MCP servers in Cascade and approve the sign-in when prompted.
{
"mcpServers": {
"wpterminal": {
"serverUrl": "https://wpterminal.com/api/mcp"
}
}
}Other desktop clients
Sign inCline, Roo Code and any client that only runs local (stdio) servers.
Other desktop clients
Sign inCline, Roo Code and any client that only runs local (stdio) servers.
- Use the mcp-remote bridge. It runs locally, opens the WPTerminal sign-in in your browser and forwards requests to https://wpterminal.com/api/mcp.
- Requires Node.js 18 or later.
{
"mcpServers": {
"wpterminal": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://wpterminal.com/api/mcp"]
}
}
}API, scripts & automations
API keyClaude API, OpenAI API, n8n, CI jobs and custom agents that cannot open a browser.
API, scripts & automations
API keyClaude API, OpenAI API, n8n, CI jobs and custom agents that cannot open a browser.
- Create an API key in Settings → AI Agents → API keys. It is shown once.
- Send it as a bearer token to https://wpterminal.com/api/mcp. Store it in a secret manager, never in code.
Authorization: Bearer wpt_pat_…
API keys act as the person who created them, expire after 90 days and can be revoked at any time. Prefer OAuth whenever the client supports it.
Safety
Approvals
Reading and small content changes (drafts, alt text, media uploads, comment replies, categories and tags) run immediately. Anything that publishes, edits published content, deletes, changes plugins or settings, or runs a WP-CLI command that changes the site waits for a person to approve it in Approvals.
Approving a kind of action covers later actions of the same kind on that site for 30 days. Approving the WP-CLI command “plugin deactivate” lets the agent deactivate other plugins there without asking again. Approving “plugin update” does not approve “plugin delete”.
Deleting plugins, themes, posts or users, changing users and updating WordPress are approved one at a time, for the exact action shown, because they cannot be undone or are hard to reverse.
- Assistants that support it can ask for approval in the chat. Plugin and theme installs, activations and updates, settings and anything approved one at a time are approved in the dashboard only.
- Revoke an approval at any time from its page in Approvals. The next attempt asks again.
- A rejected or expired request is not final: the agent can ask again, and you decide again.
- Owners and admins can approve anything; operators only for sites assigned to them; editors and viewers cannot approve.
- Most content changes report an op_id and can be undone for 30 days with undo_operation. Undoing a change that needed approval needs the same approval again.
Reference
Tools
Ask in plain language and the assistant picks the tool. The labels show what happens when it is called; they come straight from the rules the gateway enforces.
Sites & diagnostics
16 toolsFind your sites, check their health and read errors without FTP or cPanel.
list_sitesRead onlyYour connected sites with their IDs. Agents call this first to get the site_id other tools need.
Try “List my connected WordPress sites.”
site_healthRead onlyWordPress, PHP and connector versions, plus installed plugins and their status.
Try “Check site health on my shop and tell me what is out of date.”
list_content_typesRead onlyThe site's post types and taxonomies, and which taxonomies apply to which post types. Needs plugin 1.2.0.
Try “Which custom post types does this site have?”
get_site_infoRead onlySite title, tagline, language, timezone and URLs.
Try “What timezone is my blog set to?”
list_pluginsRead onlyInstalled plugins with version and active status.
Try “Which plugins are inactive on my blog?”
get_error_logRuns immediatelyRecent lines from the log WordPress is set to write (WP_DEBUG_LOG) or the PHP error log. Passwords, tokens and server paths are masked.
Try “Show the last 30 lines of the error log and explain the fatal error.”
connection_diagnosticsRead onlyExplains why a connection fails: Application Passwords switched off by a security plugin, a revoked credential, or the latest refused sign-in and its reason.
Try “Why can't WPTerminal connect to my blog?”
discover_wp_endpointsRead onlyLists the abilities Cmdlane Agent Link exposes on the site through the WordPress Abilities API, with their input schemas.
Try “What abilities does this site expose?”
multi_site_checkRead onlyRuns one read-only tool on every site you can access, or on the sites you name, and returns a combined report. Changes nothing.
Try “Check site health on all my client sites and list the ones with problems.”
multi_site_orchestrateApprove once per siteRuns one tool that changes something on every site you can access, or on the sites you name. Each site's front page and connection are checked before and after; a site already failing is skipped, and the run stops after the first site that gets worse.
When it asks: Each site's change asks for approval, the same as running it on that site alone.
Try “Update all plugins on my client sites, two at a time, and stop if any site breaks.”
start_multi_site_checkRead onlyThe same read-only check across sites, but it keeps going after the chat closes and saves each site's result as it finishes.
Try “Start a background health check of all 40 client sites.”
start_multi_site_jobRuns immediatelyA change across many sites that keeps going after the chat closes and saves each site's result as it finishes. One organization can run three jobs at a time.
When it asks: Each site's change follows that site's approval rules. For an unattended run, approve the kind of action on each site first.
Try “Start a job that updates all plugins on my 20 client sites and stops if a site breaks.”
job_statusRead onlyProgress and per-site results of a job, or your 10 most recent jobs.
Try “How is the plugin update job doing?”
cancel_jobRuns immediatelyStops a job before the next site starts.
Try “Cancel the running job.”
review_approvalRead onlyShows a pending approval as a panel with Approve and Reject buttons inside Claude, ChatGPT and other clients with MCP Apps. Critical actions stay dashboard-only.
Try “Show me that approval here so I can approve it.”
decide_approval_in_panelRuns immediatelyCalled by the approval panel's buttons, with a one-time token only the panel receives. Assistants cannot use it on their own.
Try “(used by the panel)”
Content, menus & taxonomy
14 toolsDraft, edit and organise posts, pages, categories and menus.
list_postsRead onlyPosts or pages filtered by status, with pagination.
Try “Show my five most recent drafts.”
get_postRead onlyFull content, excerpt and status of one post.
Try “Get post 42 so we can rewrite the intro.”
create_postRuns immediatelyCreates a post or page from HTML or block markup.
When it asks: Drafts, pending and private posts or pages are created straight away. Publishing, scheduling, or creating other post types (for example block theme templates) asks for approval.
Try “Draft a post titled 'Ten WordPress speed fixes' with an outline.”
validate_block_contentRead onlyChecks block-editor content before saving: unclosed or mismatched blocks, broken attribute JSON, block types the site does not have, wrong attribute types and blocks not allowed for the post type. Saving tools run the same check and refuse broken content. Needs plugin 1.1.0.
Try “Check this block markup before you save it to post 42.”
update_draft_titleRuns immediatelyChanges the title of a draft post.
Try “Rename draft 51 to 'Spring launch checklist'.”
update_postApprove once per siteEdits title, content, excerpt or status of an existing post.
Try “Add a conclusion to post 15.”
replace_textRuns immediatelyReplaces exact text in a post's content, title or excerpt, a post meta value (including Elementor, Bricks and Breakdance layouts), or a text option. Each match must be unique; if one edit fails, nothing changes.
When it asks: Dry runs run straight away. Saving asks for approval; editing an option always does.
Try “In post 15, change 'free shipping over $50' to 'free shipping over $75'.”
trash_postApprove once per siteMoves a post or page to the trash. It can be restored from WordPress.
Try “Trash the old staging announcement, post 88.”
list_termsRead onlyLists categories, tags and custom taxonomy terms.
Try “Which categories does my blog have?”
manage_termsRuns immediatelyCreates a category, tag or custom taxonomy term.
Try “Create a 'Tutorials' category.”
get_menusRead onlyNavigation menus and their items.
Try “Show the items in my header menu.”
set_post_termsApprove once per siteSets, adds or removes a post's categories, tags or custom taxonomy terms. The terms must exist. Needs plugin 1.2.0.
Try “Put post 42 in the Tutorials category and tag it wordpress.”
create_menuRuns immediatelyCreates an empty navigation menu. Needs plugin 1.2.0.
Try “Create a Footer menu.”
update_menuApprove once per siteAdds a custom link, a page or post, or a category to a menu, or changes or removes a menu item (posts, categories, changes and removals need plugin 1.2.0).
Try “Add the Pricing page to the header menu under Products.”
SEO, media & performance
11 toolsMeta data for Yoast, Rank Math and AIOSEO, image alt text and cache purges.
get_seo_dataRead onlySEO title, description, focus keyword and canonical for a post.
Try “Read the SEO title and description for post 10.”
update_seo_dataApprove once per siteWrites SEO title, description, focus keyword or canonical.
Try “Write a meta description for post 10 targeting 'AI WordPress automation'.”
list_mediaRead onlyMedia library items with URL, type, alt text and the post each is attached to. Needs plugin 1.2.0.
Try “List the last 10 images in the media library.”
list_media_without_altRead onlyMedia library images with no alt text.
Try “List images without alt text.”
upload_media_from_urlRuns immediatelyImports a public image or file into the media library, optionally with alt text and attached to a post. SVG files are sanitized.
Try “Add https://example.com/team.jpg to the media library with alt text 'Our team'.”
search_openverse_imagesRead onlySearches Openverse for openly licensed photos (CC0 and Creative Commons, commercial use by default). Each result comes with the credit to store in the caption when you import it with Upload from URL.
Try “Find three wide photos of a coffee shop interior I can use commercially and add the best one to the media library.”
read_media_pdfRead onlyReads the text of a PDF in the media library, page by page. Scanned PDFs without a text layer return no text.
Try “Read the menu PDF (media 512) and turn it into a Menu page draft.”
update_media_altRuns immediatelySets alt text, title or caption on an image.
Try “Set the alt text on image 204 to describe the product screenshot.”
flush_cacheApprove once per sitePurges LiteSpeed, WP Rocket, W3 Total Cache, WP Super Cache, Autoptimize and object caches.
Try “Flush the cache so the new header shows.”
run_lighthouse_auditRead onlyGoogle Lighthouse through PageSpeed Insights: performance, accessibility, best-practices and SEO scores, Core Web Vitals and the biggest fixes. The page must be public.
Try “Run a mobile Lighthouse audit on my home page and explain the three biggest problems.”
fetch_page_htmlRead onlyA public page as a visitor gets it: status, caching headers, title, meta tags, headings, images without alt, and the text or HTML. Scripts are not run.
Try “Fetch /pricing and tell me if the canonical and meta description are right.”
Saved skills
4 toolsInstructions your organization saves for its agents (house style, site conventions, workflows), plus built-in workflows. Also offered as prompts in clients that support them. Manage them under Skills in the dashboard.
list_skillsRead onlyYour organization's skills and the built-in workflows.
Try “Which skills do we have?”
get_skillRead onlyThe full instructions of one skill.
Try “Load our blog-style skill and use it for this post.”
save_skillRuns immediatelySaves instructions for future sessions in your organization. Saving under an existing name replaces it.
Try “Save the style rules I just gave you as a skill called blog-style.”
delete_skillRuns immediatelyDeletes one of your organization's skills.
Try “Delete the old-launch-checklist skill.”
WooCommerce
5 toolsProducts, orders, customers and coupons. Order and customer data needs a shop manager or administrator connection.
get_wc_productsRead onlyCatalogue with price, SKU and stock.
Try “Which products have fewer than five in stock?”
get_wc_ordersRead onlyRecent orders with status, totals and line items.
Try “Show the five latest processing orders.”
get_wc_customersRead onlyCustomers with order count and total spend.
Try “Who are my top ten customers by spend?”
list_wc_couponsRead onlyCoupons with usage counts and expiry.
Try “Which coupons are active?”
create_wc_couponApprove once per siteCreates a percentage or fixed discount coupon.
Try “Create a 20% coupon SUMMER20 expiring 31 August.”
Comments & forms
4 toolsModerate the community and read leads.
get_commentsRead onlyComments filtered by status.
Try “Show comments waiting for moderation.”
moderate_commentRuns immediatelyApproves, holds, spams or trashes a comment, or restores one from the trash or spam (restore needs plugin 1.2.0).
When it asks: Approving or holding runs straight away. Marking as spam or trash asks for approval.
Try “Approve the genuine questions and spam the rest.”
reply_commentRuns immediatelyPosts a reply as the connected user.
Try “Thank the commenter on comment 35.”
get_form_entriesRead onlyRecent entries from Gravity Forms, WPForms, Contact Form 7 (Flamingo) and Fluent Forms. Administrator connection only.
Try “Show this week's contact form submissions.”
Plugins, WP-CLI & advanced
6 toolsSite administration through WP-CLI commands that run inside WordPress, plus builder and store changes. Anything that changes the site waits for approval.
wp_cli_readRead onlyRuns a read-only WP-CLI command inside WordPress (no WP-CLI install needed): plugin, theme, user, option, post and cron lists, core version and update checks, database size, and help. Needs "Allow administrative tools" turned on in WordPress (Agent Link > Connection).
Try “Which plugins have updates available?”
wp_cliApprove once per siteRuns a WP-CLI command that changes the site, inside WordPress (no WP-CLI install needed): plugins, themes, users, options, posts, terms, comments, cron, caches and core updates. Read commands go through WP-CLI (read). Needs "Allow administrative tools" turned on in WordPress (Agent Link > Connection).
When it asks: Every command needs approval, and approving one (for example 'plugin update') covers that command on that site for 30 days. Deleting, user changes and core updates are approved one exact command at a time. Creating administrators, setting passwords and editing site URLs are always refused, and no SQL is accepted. Clients that support MCP elicitation can approve non-critical commands in the chat.
Try “Update all plugins on my blog.”
propose_actionApprove once per siteSaves Elementor, Bricks, Breakdance or Beaver Builder layouts through the builder, and updates WooCommerce products and orders.
When it asks: Each kind of change is approved once per site for 30 days.
Try “Change the price of product 52 to 19.99.”
undo_operationApprove every timeReverses one earlier content change by its operation ID: post fields and status, post meta and SEO fields, text options, comment status, page builder layouts, trashed and created posts. Refuses, changing nothing, if the content was edited again since. Changes stay undoable for 30 days. Needs plugin 1.2.0.
When it asks: Runs straight away when the original change did; asks again when the original change was approved.
Try “Undo the last change you made to the About page.”
check_op_statusRead onlyTells the agent whether an approval request was approved, rejected or used, or whether a change whose response was lost was made on the site.
Try “Check whether operation cmv66f5b00 was approved.”
get_page_builder_dataRead onlyThe Elementor, Bricks, Breakdance or Beaver Builder layout of a page.
Try “Read the Elementor data for page 12.”
Reference
WP-CLI commands
The plugin emulates these WP-CLI commands in PHP inside WordPress, so they work on any host, including shared hosting without WP-CLI, and never start a process. They need Allow administrative tools, which an administrator turns on when connecting or under Agent Link → Connection. Commands that run code, run SQL or rewrite the database (eval, shell, config, search-replace, db query, db import) do not exist, and flags that load code (--exec, --require) are refused. Ask for wp help to see usage for each command.
wp helpwp pluginwp themewp corewp cachewp transientwp rewritewp cronwp optionwp postwp termwp commentwp userwp rolewp capwp menuwp widgetwp sidebarwp sitewp languagewp mediawp maintenance-modewp db- No SQL is accepted:
db tablesanddb sizeare the only database commands. Options that may hold passwords, tokens or API keys (including the AI connector keys) are never read or changed. - Always refused, whatever is approved: creating or changing administrators, setting passwords, changing options that control site URLs, access or active code, deleting the active theme, and deactivating or deleting Cmdlane Agent Link.
Trust
Security
The short version. The security model page has the full detail.
Signed changes
Every change WPTerminal sends is signed and checked by the plugin, bound to your site, one operation and the exact request. A leaked Application Password cannot change anything.
Your permissions, no extra user
Agents act with the WordPress role of the person who connected the site, through an Application Password on that account, content-only unless an administrator allows administrative tools. Some actions, like creating users, are always refused.
Encrypted credentials
Site Application Passwords are encrypted with AES-256-GCM and bound to your organization and site.
Standard sign-in
AI clients connect with OAuth 2.1 and PKCE. API keys are stored only as hashes and shown once.
Roles and site access
Owners, admins, operators, editors and viewers, with optional per-site access for team members.
Audit log
Every tool call is recorded with who ran it, on which site and the result, and kept for 12 months on Pro and Agency, 6 on Free.
Safe outbound requests
The gateway refuses private, loopback and cloud-metadata addresses, including through DNS tricks.
Undo for 30 days
Content changes keep a snapshot on your site. Undo refuses rather than overwrite anything changed since.
Per-ability switches
An administrator can turn off any single ability under Agent Link → Abilities. The plugin's write abilities are never offered to other MCP servers on the site.
Revocable at any time
Disconnect an agent, revoke an API key or an approval, or disconnect a site from the dashboard or wp-admin; disconnecting revokes the site's Application Password.
Help
Troubleshooting
I can't sign in.
Sign-in is with Google only for now. Use the Google account with the same email address as your WPTerminal account. If your address is not a Google account, or Google says the account could not be linked, contact [email protected].
The client says it couldn't register or sign in with WPTerminal.
Remove the connector and add it again with the exact URL above. If it keeps failing, contact support with the time of the attempt so we can find it in the logs.
Nothing happens after clicking Allow access.
Start the connection again from your AI client and approve within a few minutes. Desktop and command-line clients stop waiting for the browser after a short time.
“No connected WordPress site found.”
Connect the site first: in wp-admin open Agent Link → Connection and click Connect to WPTerminal. Then ask the agent to call list_sites and use that site_id.
“Your account cannot connect this site” or “already connected” on WordPress's Authorize Application screen.
Connect from an account that can write posts (Author or higher). If the site is already connected through someone else's account, that person or an administrator must disconnect it first under Agent Link → Connection. WPTerminal asks you to update the plugin if it is older than 1.0.2.
“The site connector could not be reached.”
Check that the site is public over HTTPS and Cmdlane Agent Link is active. In wp-admin, Agent Link → Connection → Test the REST API shows whether a security plugin, firewall or CDN answers instead of WordPress. Subdirectory installs and plain permalinks work without changes.
“The site credential is invalid” or a cmdlane_auth_… error.
The connection's Application Password was deleted, the account it belongs to was removed, or the site was connected again elsewhere. Reconnect from Agent Link → Connection. The connection check there names the exact cause.
“Administrative tools are turned off” (cmdlane_admin_tools_off).
WP-CLI and the error log need Allow administrative tools. An administrator can turn it on under Agent Link → Connection; content tools work without it.
“An administrator of this site turned off …” (cmdlane_ability_disabled).
An administrator switched that ability off on the site. Turn it back on under Agent Link → Abilities in wp-admin; site_health lists what is turned off. Switches apply to every connection to that site, including administrators'.
Undo is refused.
cmdlane_undo_conflict means something was changed again after that operation; nothing is undone, so a later edit is never overwritten. cmdlane_undo_not_found means the operation changed nothing undoable, failed, or is older than 30 days. Undoing a change that needed approval needs approval again. Undo needs Cmdlane Agent Link 1.2.0.
“… needs Cmdlane Agent Link 1.x or newer on this site.”
That tool uses an ability added in a newer plugin version. Update Cmdlane Agent Link from Plugins in wp-admin; nothing else changes.
A change is refused with cmdlane_proof_… .
The site could not verify WPTerminal's signature on the change. Update Cmdlane Agent Link to the latest version and check the site's clock. If the message names "aud", the site address changed: reconnect. Otherwise contact support; trying again will not help.
“Human approval required” keeps appearing.
Open Approvals in the dashboard, approve the request, then ask the agent to try again. Rejected, revoked and expired approvals ask again on the next attempt.
“Viewers have read-only access.”
Your role in the organization is Viewer. Ask an owner or admin to change your role in Settings → Team & Access.
“This organization has used all 100 changes included in the Free plan today.”
Free allows 100 site changes a day; reads never count. The limit resets at midnight UTC, or upgrade in Settings → Plan & Billing. Pro has a fair-use ceiling of 5,000 changes a day that only stops runaway loops; write to us if you need more.
“… is not included in the Free plan” (FEATURE_NOT_IN_PLAN).
Page builder changes, running a tool across many sites, background jobs and team members need Pro or Agency. The message names the plan that includes it. Approvals for such actions cannot be approved until the plan includes them.
Prompt library
Not sure what to ask?
The prompt library has ready-made workflows for SEO, alt text, content drafts and cache purges.
Open the prompt library