mcp-mcp-locks
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-mcp-locks claim browser profile playwright1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-locksinstalled and on PATH (or its path passed via theMCP_LOCKS_BINenv var). The wrapper requires a version that supports--jsonoutput.
Install
git clone https://github.com/mattbaylor/mcp-mcp-locks.git
cd mcp-mcp-locks
npm install
npm run buildConfigure 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 |
| Array of all registered instances with current status, owners, TTLs |
| Detail on a single instance (free / claimed / expired / dead_pid) |
| Acquire or refresh a lock (default 30m TTL); auto-detects owner |
| Release a claim; owner-checked unless |
| Clean up expired claims, dead-PID claims, orphaned Chromium, stale SingletonLocks |
| Health report; recommends reap when needed |
| Kill Playwright-MCP Chromium processes on demand ( |
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:trueFor 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-stealSub-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
claimorrelease— 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-locksCLI directly from a shell or scriptAny 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 toolsclaimA
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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Coordinate multiple AI agents over MCP: atomic claims, leases, shared ledger, handoffs, tasks.
Secure Linux sandboxes for AI agents, as MCP tools.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceWraps Anthropic Claude Code CLI as tools, allowing MCP clients to invoke headless Claude Code sessions.2324 npmMIT
- AlicenseNot gradedqualityDmaintenanceWraps the Tailscale CLI to enable MCP-capable AI agents to manage devices, serve configurations, and diagnose connectivity.3MIT
- AlicenseNot gradedqualityBmaintenanceLocal 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 npmMIT
- FlicenseNot gradedqualityBmaintenanceWraps Oh My Pi built-in tools (read, write, edit, bash, grep, etc.) as MCP tools, enabling file operations, shell commands, web search, and agent coordination.-