An MCP server that gives Claude the ability to perform multiple find-and-replace operations in a single tool call with guaranteed atomicity -- all edits succeed or none apply.
Built by Essential AI Solutions for Claude Code and Claude Desktop.
Claude's built-in Edit tool handles one find-and-replace per call. When renaming a variable across a file or refactoring multiple files, that means dozens of individual tool calls -- each consuming context tokens and adding latency.
Multi Edit batches them into a single call:
Without multi_edit: 105 tool calls | 15,750 tokens
With multi_edit: 21 tool calls | 7,850 tokens (-80% calls, -50% tokens)
With multi_edit_files: 6 tool calls | 4,550 tokens (-94% calls, -71% tokens)
Benchmarks run on realistic scenarios (bulk rename, logging migration, cross-file refactor). See benchmarks/results/BENCHMARK-REPORT.md for full details.
Add .mcp.json to your project root:
{
"mcpServers": {
"Multi Edit from Essential AI Solutions (essentialai.uk)": {
"command": "npx",
"args": ["-y", "@essentialai/mcp-multi-edit"]
}
}
}Restart Claude Code. Then add the included CLAUDE.md to your project root so Claude automatically prefers multi_edit over the built-in Edit tool:
## Editing Files
When making multiple edits to the same file or across multiple files,
prefer using the `multi_edit` and `multi_edit_files` MCP tools over
the built-in Edit tool. These batch edits atomically in a single call.That's it -- Claude will now use multi_edit whenever it's the right tool for the job.
Display name: Claude Code uses the key name in
mcpServersas the server's display name. You can change the key to any name you prefer.
Alternative: One-liner via CLI:
claude mcp add --transport stdio multi-edit -- npx -y @essentialai/mcp-multi-editNote: The CLI only accepts simple names (letters, numbers, hyphens, underscores). For the full branded display name, use the
.mcp.jsonapproach above.
Add to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"Multi Edit from Essential AI Solutions (essentialai.uk)": {
"command": "npx",
"args": ["-y", "@essentialai/mcp-multi-edit"]
}
}
}Restart Claude Desktop.
Full installation guide: docs/installation.md
Batch multiple find-and-replace operations on one file. Edits apply sequentially and atomically.
{
"file_path": "/project/src/app.ts",
"edits": [
{ "old_string": "const oldName = getValue()", "new_string": "const newName = getValue()" },
{ "old_string": "console.log", "new_string": "logger.info", "replace_all": true }
]
}| Parameter | Type | Default | Description |
|---|---|---|---|
file_path |
string | required | Absolute path to the file |
edits |
array | required | Find-and-replace operations (applied in order) |
edits[].old_string |
string | required | Text to find (exact match) |
edits[].new_string |
string | required | Replacement text |
edits[].replace_all |
boolean | false |
Replace all occurrences |
dry_run |
boolean | false |
Preview changes without applying |
backup |
boolean | true |
Create .bak backup before editing |
Coordinate edits across multiple files. If any file fails, all files are rolled back automatically.
{
"files": [
{
"file_path": "/project/src/types.ts",
"edits": [
{ "old_string": "interface UserData {", "new_string": "interface UserProfile {" }
]
},
{
"file_path": "/project/src/api.ts",
"edits": [
{ "old_string": "UserData", "new_string": "UserProfile", "replace_all": true }
]
}
]
}| Parameter | Type | Default | Description |
|---|---|---|---|
files |
array | required | Array of file edit operations |
files[].file_path |
string | required | Absolute path to the file |
files[].edits |
array | required | Edits for this file (same format as above) |
dry_run |
boolean | false |
Preview changes without applying |
Full usage guide with examples: docs/usage.md
- Atomic operations -- all edits succeed or none apply, no partial state
- Multi-file rollback -- if any file fails, all previously changed files are restored
- Dry-run preview -- see exactly what would change before committing
- Automatic backups --
.bakfiles created before every edit (disable withbackup: false) - Structured errors -- machine-readable error codes with recovery hints for automatic retry
- Conflict detection -- warns when
old_stringmatches multiple locations - Path validation -- absolute path enforcement, symlink resolution, existence checks
| Code | Retryable | Description |
|---|---|---|
MATCH_NOT_FOUND |
Yes | old_string not found in file |
AMBIGUOUS_MATCH |
Yes | old_string matches multiple locations |
VALIDATION_FAILED |
Yes | Invalid input schema |
FILE_NOT_FOUND |
No | File does not exist |
PERMISSION_DENIED |
No | Insufficient file permissions |
BACKUP_FAILED |
No | Could not create backup file |
When retryable is true, Claude reads the recovery_hints in the response, adjusts the input, and retries automatically.
Troubleshooting guide: docs/troubleshooting.md
- Node.js 20 or later
- Claude Code or Claude Desktop
npm install # Install dependencies
npm run build # Compile TypeScript
npm test # Run 264 tests
npm run test:coverage # Coverage report (90%+)
npm run benchmark # Run benchmark suite
npm run dev # Watch modesrc/
index.ts # MCP server entry (stdio transport)
server.ts # Server factory and tool registration
tools/
multi-edit.ts # multi_edit tool handler
multi-edit-files.ts # multi_edit_files tool handler
core/
editor.ts # File editing engine (atomic read-modify-write)
validator.ts # Zod input validation schemas
reporter.ts # Result formatting and diff generation
errors.ts # Error classification and envelope creation
types/
index.ts # TypeScript type definitions
| Document | Description |
|---|---|
| Installation Guide | All setup options for Claude Code and Claude Desktop |
| Usage Guide | Detailed tool reference with examples |
| Troubleshooting | Common issues and solutions |
| Changelog | Version history |
| Benchmark Report | Performance measurements |
PolyForm Noncommercial License 1.0.0
Free for personal and non-commercial use. For commercial licensing, contact support@essentialai.uk.
Built by Essential AI Solutions