[BUG] Docker-based MCP server containers not stopped when session ends

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/1935
2. https://github.com/anthropics/claude-code/issues/16397
3. https://github.com/anthropics/claude-code/issues/26658

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

• I don't see the issue in https://github.com/anthropics/claude-code/issues/1935, once my mcp processes are correctly terminated when I check with ps aux. My issue is about docker containers as I described.
• https://github.com/anthropics/claude-code/issues/16397 is using github-mcp-server, which is not my case.
• https://github.com/anthropics/claude-code/issues/26658 is same as https://github.com/anthropics/claude-code/issues/1935

I have exactly same issue on macOS

+1, same issue on MacOS, can we prioritize this?

A Stop hook can clean up Docker containers when the session ends:

docker ps --filter "name=mcp" --format '{{.ID}}' 2>/dev/null | while read id; do
    docker stop "$id" 2>/dev/null
    echo "Stopped MCP container: $id" >&2
done
docker ps --filter "label=started-by=claude-code" --format '{{.ID}}' 2>/dev/null | while read id; do
    docker stop "$id" 2>/dev/null
done
exit 0

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
if echo "$COMMAND" | grep -qE 'docker\s+run'; then
    CONTAINER=$(docker ps -l --format '{{.ID}}' 2>/dev/null)
    if [ -n "$CONTAINER" ]; then
        echo "$CONTAINER" >> "$HOME/.claude/.docker-containers"
    fi
fi
exit 0

{
  "hooks": {
    "Stop": [{"hooks": [{"type": "command", "command": "bash ~/.claude/hooks/docker-cleanup.sh"}]}],
    "PostToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "bash ~/.claude/hooks/docker-tag.sh"}]}]
  }
}

The Stop hook fires on session end (normal completion, /exit, Ctrl+C) and stops any MCP containers. The PostToolUse hook tracks which containers were started during the session for reliable cleanup.

Workaround: Wrapper script + per-session PID watchdog

Each Docker MCP points to a small wrapper script instead of docker directly. The wrapper:

1. Captures CLAUDE_PID=$PPID — the Claude Code process that spawned it.
2. Generates a unique container name scoped to that PID.
3. Spawns a detached watchdog using Python's os.setsid() (works on both macOS and Linux) that polls kill -0 $CLAUDE_PID every 2 s. When Claude exits by any means, the watchdog calls docker stop on that container and terminates itself.
4. execs docker run with the named container + two labels.

Step-by-step setup

1. Create the wrapper script

Create .claude/scripts/mcp-docker-launch.sh in your project (adjust path as needed):

#!/usr/bin/env bash
# Launch a Docker-based MCP server with a self-terminating watchdog.
# Usage in .mcp.json: set "command" to this script and pass docker image args
# (without the leading "run" -- this script adds it).
set -euo pipefail

CLAUDE_PID="$PPID"
CONTAINER_NAME="claude-mcp-${CLAUDE_PID}-$$-${RANDOM}"

# Detached watchdog: polls Claude Code's PID and stops the container when it dies.
# Uses Python's os.setsid() to escape Claude's process group — setsid command is
# Linux-only and unavailable on macOS. nohup + disown prevent SIGHUP on shell exit.
nohup python3 -c "
import os, sys, subprocess, time
os.setsid()
pid, name = int(sys.argv[1]), sys.argv[2]
while True:
    try:
        os.kill(pid, 0)
        time.sleep(2)
    except (ProcessLookupError, PermissionError):
        break
subprocess.run(['docker', 'stop', name], capture_output=True)
" "$CLAUDE_PID" "$CONTAINER_NAME" </dev/null >/dev/null 2>&1 &
disown || true

exec docker run -i --rm \
  --name "$CONTAINER_NAME" \
  --label claude-mcp=true \
  --label "claude-pid=${CLAUDE_PID}" \
  "$@"

Make it executable:

chmod +x .claude/scripts/mcp-docker-launch.sh

2. Update .mcp.json

For each Docker-based MCP, change "command": "docker" to the wrapper and remove the leading "run" from args (the wrapper adds it):

{
  "mcpServers": {
    "my-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/.claude/scripts/mcp-docker-launch.sh",
      "args": [
        "-e", "SOME_ENV_VAR",
        "my-docker-image",
        "--some-flag"
      ],
      "env": {
        "SOME_ENV_VAR": "value"
      }
    }
  }
}

Any Docker MCP that uses this wrapper gets automatic cleanup.

I'm on a mac, after installing the latest Docker v.4.7.30 somehow symlinks got updated and that caused mayhem.

What I had to do to fix Claude is the following:

In claude_desktop_config.json, update the "mcpServers" and "MCP_DOCKER" section

from

            "command": "docker",

to

            "command": "/Users/my-name/.docker/bin/docker",

I did have a global symlink to "/Users/my-name/.docker/bin/docker", but apparently Claude cannot pick that up from my .bash_profile.

So hardcoding the full path to the Docker executable did the trick..

Thanks for the report. This is the same issue as #1935 (stdio MCP child processes not terminated on exit). Consolidating tracking there.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.