lifeline

A tiny watchdog MCP server for Claude Code on Windows.

When the MCP server Claude Code is working through crashes or hangs, its tools stop responding and there is no tool left to call to fix it, so the session stalls until someone steps in. lifeline is a second MCP server that removes that dead end. It runs separately, on system Python, with zero dependencies, so it stays up when the other one goes down. Claude can call its reboot tool to kill the stuck server and drive Claude Code's /mcp reconnect, then pick the task back up on its own, with a fallback shell and file reader to use in the meantime.

It is deliberately small and self-contained: one stdlib-only file, raw JSON-RPC over stdio, no MCP SDK. There is almost nothing in it that can break.

Requirements

• Windows. It uses Win32 (via ctypes) to enumerate processes and to inject keystrokes into the Claude Code terminal. It will not run on macOS or Linux as-is.
• Claude Code. The reboot flow drives Claude Code's /mcp menu.
• Python 3.8+ on PATH. No pip packages.

Tools

• reboot - kill the target MCP server and trigger a Claude Code /mcp reconnect, which relaunches it. Use when the target's tools are failing.
• status - report whether the target server and Claude Code are running, with PIDs and the process ancestry lifeline is using.
• shell - run a shell command. A fallback terminal for when the target is down.
• read_file - read a file. A fallback for when the target's file tools are down.

How reboot works

1. Find the Claude Code process by walking up lifeline's own process tree.
2. Find the target server process by matching TARGET_MATCH against process command lines, limited to the current Claude Code session's process tree so it never touches another session's server.
3. Kill it (unless you pass kill_first=false).
4. Inject keystrokes into the Claude Code terminal: /mcp then Enter to open the server menu, Enter to select the server, Down to the Reconnect action, Enter to fire it. Claude Code reconnects, which relaunches the server.

Step 4 is the fragile part. See Adapting below.

Install

lifeline is one file. Point Claude Code at it and run it with your system Python, not the target server's virtualenv. That is the whole point: it should survive if the target's environment is what broke. example_config.json shows the shape:

{
  "mcpServers": {
    "lifeline": {
      "command": "python",
      "args": ["C:/path/to/lifeline/server.py"],
      "env": {
        "LIFELINE_TARGET_MATCH": "my-mcp/server.py",
        "LIFELINE_TARGET_LABEL": "my-mcp"
      }
    }
  }
}

Adapting it to your setup

Everything you need to change is the CONFIG block at the top of server.py, or the matching LIFELINE_* environment variables:

• TARGET_MATCH - a substring that uniquely identifies your server's launch command. server.py works if it is your only Python MCP server; if you run several, narrow it (for example my-mcp/server.py, or a distinctive folder name). Matching is already limited to your Claude Code session's process tree.
• TARGET_LABEL - cosmetic name used in status and log messages.
• SHELL_CWD - working directory for the shell tool.

The /mcp menu choreography is the part most likely to need tweaking. The injection in run_injection() assumes the target is the FIRST server listed in Claude Code's /mcp menu and that Reconnect is one Down from the top (Enter, Down, Enter). If you have several MCP servers, a different menu order, or a Claude Code build whose menu differs, adjust that stage sequence, and the DELAY_* timing constants if injection is racing the UI. lifeline writes an inject.log next to server.py recording each stage, which makes tuning quick.

Safety

This is a recovery tool, so it is intentionally powerful and unsandboxed: shell runs arbitrary commands, read_file reads any path, and reboot kills processes and types into your terminal. Only ever run it locally, as your own MCP server. Do not expose it over a network.

License

MIT. See LICENSE.