Multi Edit MCP Server

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.

Why Multi Edit?

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.

Quick Start

Claude Code

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 mcpServers as 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-edit

Note: The CLI only accepts simple names (letters, numbers, hyphens, underscores). For the full branded display name, use the .mcp.json approach above.

Claude Desktop

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

Tools

multi_edit -- Single file, multiple edits

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 |

multi_edit_files -- Multiple files, one atomic operation

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

Features

• 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 -- .bak files created before every edit (disable with backup: false)
• Structured errors -- machine-readable error codes with recovery hints for automatic retry
• Conflict detection -- warns when old_string matches multiple locations
• Path validation -- absolute path enforcement, symlink resolution, existence checks

Error Codes

| 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

Requirements

• Node.js 20 or later
• Claude Code or Claude Desktop

Development

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 mode

Project Structure

src/
  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

Documentation

| 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 |

License

PolyForm Noncommercial License 1.0.0

Free for personal and non-commercial use. For commercial licensing, contact [email protected].

Built by Essential AI Solutions