Skip to main content
Glama
mcp-mcp-locks
by mattbaylor

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

Related MCP server: mcp-tailscale

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

Available Tools

6 tools
claimA

Acquire (or refresh) a lock on an MCP instance. Returns ok:true with action=claimed (fresh) or refreshed (same owner re-claiming). If another owner holds the lock, returns ok:false with error=denied and details about the current owner — pick a different instance or pass force=true to steal (use sparingly; the current holder will get unexpected behavior). Owner is auto-detected from the calling session (OpenCode run ID, Claude Code session ID, or shell PPID); pass explicit owner to override. Default TTL is 30 minutes.

Inputs: instance (required), ttl, note, force, +1 more.

doctorA

Report the health of mcp-locks: state file paths, active claim count, expired claims, dead-PID claims, Chromium process and SingletonLock counts, and whether reap is recommended. Use this for diagnostics when claims aren't behaving as expected, or as a quick liveness check.

Inputs: no named parameters.

listA

List all registered MCP instances and their current claim status. Returns an array of records: each includes instance name, owner (or null if free), owner_pid, claimed_at, expires_at, note, age_seconds, ttl_remaining_seconds, alive (PID liveness), and status (free|claimed|expired|dead_pid). Use this to see what's available before claiming.

Inputs: no named parameters.

reapA

Clean up expired claims, dead-PID claims (for session-based owners), orphaned Chromium processes from prior MCP runs, and stale SingletonLock files. Idempotent — safe to call any time. Returns counts of what was cleaned up. Run this if doctor reports reap_recommended=true, or after a client crash leaves locks/processes behind.

Inputs: no named parameters.

releaseA

Release a previously-claimed lock so other sessions can claim it. Returns ok:true with action=released (or already_free if it wasn't claimed). If the lock is owned by someone else, returns ok:false with error=owner_mismatch — pass force=true to override (rare; usually a sign you should let the real owner finish). Owner is auto-detected the same way as claim.

Inputs: instance (required), force, owner.

whoA

Get detail on a single MCP instance: who owns it, when it was claimed, how much TTL remains, and whether the owning PID is still alive. Exit code 0 if owned, 1 if free, 2 if the instance name is not registered. Useful before claiming to decide whether to wait, pick a different instance, or force-steal.

Inputs: instance (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.8/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct purpose: claim/release manage locks, list/who provide overview vs. detail, doctor diagnoses health, and reap cleans up. No functional overlap.

    Naming Consistency5/5

    All tool names are single verbs (claim, doctor, list, reap, release, who), forming a consistent pattern. The use of 'doctor' as a verb is unconventional but fits the uniformity.

    Tool Count5/5

    Six tools cover the full lifecycle of lock management without being excessive. Each tool adds clear value, and the count is well-scoped for the domain.

    Completeness5/5

    The set includes claim, release, list, inspect (who), diagnose (doctor), and cleanup (reap). Refresh is built into claim, and force options handle edge cases. No obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Local MCP server that lets agents save copied secrets into 1Password and use approved fields through encrypted handles without plaintext secret tool arguments or responses. Includes a local permissions dashboard and optional service-account access for unattended work. Requires the 1Password CLI and runs on your computer.
      110 npm
      MIT