mcp-mcp-locks

An MCP server that wraps the mcp-locks CLI, exposing its coordination primitives as native MCP tools.

Use case: Multiple AI agents (across OpenCode, Claude Code, devcontainer/sandboxed runtimes, etc.) need to coordinate access to MCP instances that hold exclusive OS resources — Playwright Chromium profile dirs, the figma-desktop port, any future single-resource MCP server. mcp-locks solves this via a host-global state file and a small bash CLI. This server makes its operations discoverable in every MCP client's tool surface, so an agent that's been told "use Playwright instance X" can also see claim/release as first-class tools rather than something to remember to shell out to.

Why a wrapper?

The mcp-locks CLI works fine from a shell. But rules like "agents must claim before using" have been re-discovered as broken across many sessions because the agent has to know the convention exists and remember to invoke it. Exposing the operations as MCP tools puts them directly in the agent's function roster — claim/release/list/who become discoverable the same way playwright_browser_navigate is. Discoverability is the highest-leverage fix for "agent forgot the convention."

This server is thin by design: every tool shells out to mcp-locks --json and returns the structured envelope. State, locking, owner detection, and reaping all stay owned by the upstream binary (single source of truth).

Prerequisites

• Node.js 20+
• mcp-locks installed and on PATH (or its path passed via the MCP_LOCKS_BIN env var). The wrapper requires a version that supports --json output.

Install

git clone https://github.com/mattbaylor/mcp-mcp-locks.git
cd mcp-mcp-locks
npm install
npm run build

Configure your MCP client

OpenCode (opencode.json or opencode.jsonc)

{
  "mcp": {
    "mcp-locks": {
      "type": "local",
      "command": ["node", "/path/to/mcp-mcp-locks/dist/index.js"],
      "enabled": true
    }
  }
}

Claude Code (.claude.json)

{
  "mcpServers": {
    "mcp-locks": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-mcp-locks/dist/index.js"]
    }
  }
}

Custom mcp-locks binary location

If mcp-locks is not on the spawned process's PATH (common in sandboxed agent runtimes with minimal env), set MCP_LOCKS_BIN:

{
  "mcp": {
    "mcp-locks": {
      "type": "local",
      "command": ["node", "/path/to/mcp-mcp-locks/dist/index.js"],
      "enabled": true,
      "environment": {
        "MCP_LOCKS_BIN": "/Users/you/bin/mcp-locks"
      }
    }
  }
}

Tools

Tool	Purpose
list	Array of all registered instances with current status, owners, TTLs
who	Detail on a single instance (free / claimed / expired / dead_pid)
claim	Acquire or refresh a lock (default 30m TTL); auto-detects owner
release	Release a claim; owner-checked unless force: true
reap	Clean up expired claims, dead-PID claims, orphaned Chromium, stale SingletonLocks
doctor	Health report; recommends reap when needed
kill	Kill Playwright-MCP Chromium processes on demand (mode: 'orphans' | 'all' | 'instance', plus safety: 'idle-only' | 'force' for all mode). Per-instance kill is not implemented in v1.

Every tool returns the upstream mcp-locks --json envelope augmented with exitCode and (if present) stderr:

// success
{ "ok": true, "data": { ... }, "exitCode": 0 }

// denied
{ "ok": false, "error": "denied", "denied": { ... }, "exitCode": 2 }

Typical agent flow

1. agent calls list           -> sees which instances are free
2. agent calls claim          -> ok:true; agent proceeds with the corresponding browser tools
3. agent does its work
4. agent calls release        -> ok:true

For conflict cases:

1. agent calls claim playwright2
2. response: { ok: false, error: "denied", denied: { current_owner: "...", ttl_remaining_seconds: 1200 } }
3. agent either: claims a different instance, waits, or asks the human whether to force-steal

Sub-agent pattern

When dispatching a sub-agent to do parallel work:

• Parent claims the instance and passes the assigned name to the sub-agent
• Sub-agent uses the assigned instance's browser tools (e.g. playwright3_browser_*)
• Sub-agent does NOT call claim or release — the parent owns the lifecycle

This avoids the sub-agent's claim expiring mid-work due to a TTL shorter than the parent's task.

How it relates to mcp-locks

This server is one of several possible interfaces to the underlying coordination layer. Other valid callers:

• The mcp-locks CLI directly from a shell or script
• Any tool reading the state file at ~/.local/state/mcp-locks/state.json (read-only; never write)
• CI scripts that gate execution on a lock

All callers share the same state and the same concurrency guarantees — this wrapper doesn't add a second source of truth.

License

MIT