# mcp-multi-edit [Health: Active]

**Category:** 📂 File Systems  
**Repository:** https://github.com/eaisdevelopment/mcp-multi-edit  
**GitHub Stars:** 0  
**npm Downloads (last month):** 204  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-multi-edit

## Description
Atomic multi-file find-and-replace — 80% fewer tool calls, 50% less context usage

## Tools
Capabilities this server exposes over MCP:

- **multi_edit** — Perform multiple find-and-replace operations on a single file atomically. All edits succeed or none apply.
- **multi_edit_files** — Perform coordinated edits across multiple files atomically. All file edits succeed or none apply.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-multi-edit": {
    "command": "npx",
    "args": ["-y","@essentialai/mcp-multi-edit"]
  }
}
```

## Documentation

## What mcp-multi-edit does

The mcp-multi-edit MCP server gives Claude Code and Claude Desktop tools for applying exact text replacements to local project files. It is designed for changes such as renaming a symbol, updating repeated logging calls, or modifying related declarations and references across a codebase.

The server exposes two operations. `multi_edit` applies an ordered list of replacements to one file. `multi_edit_files` groups edits for several files into one operation. Both use literal string matching rather than describing a language-aware refactor system, so the requested text must be present in the target files.

Edits are atomic. A failed operation does not leave a partial result, and a failure during a multi-file operation restores files changed earlier in that operation. The server can also create `.bak` files before edits and return a preview without writing changes.

## How it works

Each request supplies absolute file paths and one or more edit objects. An edit identifies `old_string`, `new_string`, and an optional `replace_all` flag. Without that flag, the default behavior replaces one match; setting it replaces every matching occurrence. For a single file, edits run in the order provided, so a later edit can work with the result of an earlier one.

`multi_edit_files` accepts a list of files, with each file carrying its own ordered edit list. Its transaction covers the whole request: if one file cannot be processed, previously modified files are rolled back. The `dry_run` option on either tool reports the proposed changes without committing them.

Validation includes absolute-path enforcement, path and symlink checks, file existence checks, and input-schema validation. The server reports machine-readable error codes, including match failures, ambiguous matches, missing files, permission problems, and backup failures. Retryable responses include recovery hints for adjusting a request.

## Setup and configuration

The mcp-multi-edit MCP server requires Node.js 20 or later. It runs over the stdio MCP transport and can be launched with the published npm package using `npx`.

For Claude Code, add an MCP server entry to a project-level `.mcp.json`, with `npx` as the command and `-y @essentialai/mcp-multi-edit` as its arguments. Claude Code also supports the equivalent `claude mcp add --transport stdio` command. Restart the client after registering the server. The repository recommends adding its editing guidance to `CLAUDE.md` so Claude prefers the batch tools for multi-edit tasks.

Claude Desktop uses the same `command` and `args` values in its MCP configuration file. On macOS, the documented location is `~/Library/Application Support/Claude/claude_desktop_config.json`. No environment variables are listed as required.

## Tools and capabilities

The mcp-multi-edit MCP server provides:

- `multi_edit` for multiple sequential replacements in one absolute-path file.
- `multi_edit_files` for atomic coordinated replacements across multiple files.
- `dry_run` previews on both tools.
- Optional `.bak` creation, enabled by default for `multi_edit` edits and configurable with `backup: false`.
- Exact-match conflict detection when a requested string appears in multiple locations.
- Structured errors with retryability and recovery hints.
- Path validation, symlink resolution, and existence checks.

## Limitations and notes

The tools operate on exact text strings and require absolute paths. A missing file or insufficient permission is non-retryable, while invalid input, missing matches, and ambiguous matches are reported as retryable conditions.

The repository documents support for Claude Code and Claude Desktop and does not describe other MCP clients. Commercial use is not covered by the stated free-use terms: the project uses the PolyForm Noncommercial License 1.0.0 and directs commercial users to contact the project for licensing.

_Full upstream README: https://allmcps.com/mcp/mcp-multi-edit/readme_