mcp-lock-manager

mcp-lock-manager

An MCP server that provides file-level exclusive locking across multiple Claude Code instances. Prevents conflicts when multiple agents edit files in the same project simultaneously.

How It Works

When multiple Claude Code sessions share a project, they can clobber each other's edits. This MCP server acts as a mutex — each session acquires a lock before editing a file and releases it when done. Locks are stored in a local .locks/ directory using atomic filesystem operations.

Stale locks from crashed sessions are automatically detected via PID liveness checks and cleaned up.

Setup

1. Install & Build

git clone https://github.com/maxwellplanck/mcp-lock-manager.git
cd mcp-lock-manager
npm install
npm run build

2. Configure Claude Code

Add to your .claude/settings.json (project or user-level):

{
  "mcpServers": {
    "lock-manager": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-lock-manager/build/index.js", "--project-root", "/absolute/path/to/your/project"]
    }
  }
}

The --project-root flag tells the server which project directory to manage locks for. If omitted, it defaults to the current working directory.

You can also set the project root via environment variable:

{
  "mcpServers": {
    "lock-manager": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-lock-manager/build/index.js"],
      "env": {
        "PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Tools

lock_acquire

Acquire exclusive locks on one or more files before editing.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | paths | string[] | Yes | Project-relative file paths (use forward slashes) | | owner | string | No | Label for this session (e.g. "Agent A") |

Acquires all-or-nothing — if any file is already locked by another live session, the entire request fails with conflict details.

lock_release

Release file locks when done editing.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | paths | string[] | No | Paths to release. Omit to release all locks for this session. |

lock_list

List all active locks with owner, PID, alive status, and timestamp. Takes no parameters.

lock_cleanup

Force-remove all stale locks held by dead processes. Takes no parameters. Useful when lock_list shows locks with alive: false.

Adding to Your Workflow

For best results, add instructions to your project's CLAUDE.md telling Claude to use locks:

## File Locking

This project uses mcp-lock-manager for multi-session coordination.
Before editing any file, acquire a lock with `lock_acquire`. Release locks with `lock_release` when done.
If a lock conflict occurs, do not proceed — wait or ask the other session to release.

License

MIT