mcp-shim

A process wrapper that ensures MCP server child processes are properly terminated when the parent connection closes.

The Problem

MCP (Model Context Protocol) servers are typically spawned as child processes by host applications. When the host terminates, it should clean up these child processes. However, many MCP hosts don't properly track and terminate their child processes, leading to leaked processes that continue running in the background.

This is especially problematic for MCP servers that spawn their own subprocesses (e.g., uvx, npx, or other process launchers), as the entire process tree can be orphaned.

The Solution

mcp-shim wraps your MCP server command and:

1. Spawns the child process in its own process group
2. Transparently forwards stdin/stdout/stderr
3. Forwards signals (SIGTERM, SIGINT, SIGHUP) to the child process group
4. Kills the entire process group when stdin closes (indicating the host has disconnected)

Installation

docker pull ghcr.io/cbgbt/mcp-shim:latest

Usage

Wrap your MCP server command with mcp-shim:

mcp-shim <command> [args...]

Example: MCP Server Configuration

Without the shim, an MCP server might be configured like this:

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["some-mcp-server"]
    }
  }
}

With the shim, wrap the command to ensure proper cleanup:

{
  "mcpServers": {
    "my-server": {
      "command": "mcp-shim",
      "args": ["uvx", "some-mcp-server"]
    }
  }
}

How It Works

1. The shim spawns your command in a new process group (setpgid(0, 0))
2. Stdin, stdout, and stderr are forwarded transparently
3. When stdin reaches EOF (host disconnected), the shim sends SIGTERM to the process group, waits briefly, then sends SIGKILL
4. Signals received by the shim are forwarded to the child process group

License

MIT OR Apache-2.0