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
• How a Run Works
  • Start With a Dry Run
  • Apply the Replacement
  • Long Runs Continue in the Background
• What It Changes
  • Which Tables Are Searched
  • Serialized and Encoded Data
  • What Is Never Changed
  • Site Address Settings
• Undoing a Run
• What It Does Not Handle
• Review a Run Afterwards

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:

1. Go to Easy MCP AI > Settings and scroll to the Advanced card.
2. Under Disabled tools, clear the checkbox next to wp_privileged_search_replace_run.
3. 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:

Do a dry run of a search and replace from http://old-site.com to https://new-site.com.

The result lists, for each table and column, how many values contain the text and how many times it appears. 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 text and with the dry run turned off.

While Ask before destructive actions is on under Easy MCP AI > Settings > Access & safety, every run, including a dry run, waits for your approval. The approval request shows the whole search, the replacement and the tables in scope, and the result of the last dry run with the same settings.

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. While Ask before destructive actions is on, the cancellation waits for your approval too. 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.

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 guid column 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.