Appearance
Search and Replace Across the Database
The search and replace tool lets your AI assistant find a piece of text everywhere in your WordPress database and replace it, the way wp search-replace does from the command line. It is built for jobs like moving a site to a new domain or switching links from http:// to https://. This guide explains how a run works, what it changes and what it leaves alone.
❗ Danger: A search and replace rewrites your database and cannot be undone automatically. Take a backup of your database before you apply one.
In this article
Before You Start
The tool is wp_privileged_search_replace_run, one of the privileged tools. It is switched off until you turn it on:
- Go to Easy MCP AI > Tools and search for
wp_privileged_search_replace_run. - Enable the tool, configure Require approval, and check whether a deployment lock controls the setting.
- Click Save changes, then refresh the tool list in your AI client.
The connection your AI client uses must belong to an administrator. For which tokens and OAuth connections can reach the tool, see Privileged Tools in Easy MCP AI.
How a Run Works
Start With a Dry Run
Every run is a dry run unless the AI asks otherwise. A dry run searches the database and reports what would change, without writing anything. Ask your assistant, for example:
text
Do a dry run of a search and replace from http://old-site.com to https://new-site.com.The assistant passes the text to find as old, the replacement as new, and dry_run: true.
The result lists, for each table and column, how many values contain the text and how many times it appears. Check that the tables and columns are the ones you mean to change. Ask the assistant to include sample excerpts if you want to see a few values before and after.
Apply the Replacement
When the dry run looks right, ask the assistant to apply the same replacement. It calls the tool again with the same old, new and scope settings, changing only dry_run to false.
When Require approval applies to wp_privileged_search_replace_run under Easy MCP AI > Tools, every new run, including a dry run, waits for your approval. Deployment settings and operation-specific exceptions still apply. The approval request shows the whole search, replacement, tables in scope, and the last matching dry-run result.
Long Runs Continue in the Background
A run works for about 20 seconds inside the AI's request. A larger database needs longer, so the run continues in the background through WordPress's scheduled tasks, under the same approval. The tool then returns a job ID, and the assistant can check its progress by calling the tool with that ID. Checking progress never asks for approval.
- Only one run that writes to the database can be active on a site at a time.
- A run that makes no progress for 5 minutes is reported as stalled.
- A finished run can be checked for one day.
- The assistant can cancel a running job. When this tool requires approval, cancellation also waits for approval, subject to deployment settings and operation-specific exceptions. Tables already processed keep their changes.
What It Changes
Which Tables Are Searched
By default the tool searches every table with your site's table prefix. The assistant can narrow or widen that:
- Name specific tables, with
*and?as wildcards. - Skip tables or columns, or limit the run to certain columns.
- Search every table in the database, whatever its prefix.
- On a multisite network, a super admin can include every site's tables and the network tables. A site administrator stays limited to their own site's tables. Check that the dry run covers the sites you intend, and make sure the run that writes uses the same scope.
Serialized and Encoded Data
Many plugins store settings as serialized PHP data, which records the length of every text value. The tool opens those values, replaces the text inside them and stores them again with the correct lengths, so they keep working. It also replaces the escaped form of the text that JSON uses, such as https:\/\/.
The search is case-sensitive and matches the exact text. Regular expressions are not supported, and the search text must be at least 3 characters long.
What Is Never Changed
- Easy MCP AI's own tables and settings.
- The password column of the users table.
- The
guidcolumn of posts, unless the assistant asks to include it. WordPress uses it as a permanent identifier, so it is normally left alone. - Tables without a primary key, text columns that are part of the key, and database views.
- Stored objects of PHP classes that the tool cannot safely rewrite. These are listed in the result as skipped.
Site Address Settings
If the replacement changes the WordPress Address or Site Address settings, those two values are written last, after everything else. After a run that writes, the WordPress object cache is cleared. Page caches from a caching plugin, your host or a CDN are not purged, so clear them yourself afterwards.
Undoing a Run
There is no undo button. To reverse a run, ask the assistant to run the opposite replacement. The result of every run says whether that would restore your data exactly:
- It would not if some values already contained the new text before the run.
- It would not if the replacement was empty, because removed text cannot be found again.
In those cases, restore your database from the backup you took before the run.
What It Does Not Handle
- URL-encoded values, such as
http%3A%2F%2F. - Text that the block editor stores escaped inside block attributes, such as
&,<,>or".
Review a Run Afterwards
Each call is recorded in the Audit log, and each run that wrote to the database adds one entry to Change history when it finishes. See Using the Easy MCP AI Audit Log.