MCP Process Cleaner

Lightweight CLI for scanning and safely cleaning local Codex MCP helper process residue.

It is designed for the common case where closing a Codex window or session leaves STDIO MCP helpers such as codegraph, apifox-mcp-server, or node_repl running in the background.

Install

Use it directly with npx:

npx mcp-process-cleaner scan

Or install it globally:

npm install -g mcp-process-cleaner
mcp-cleanup scan

Quick Start

The default workflow is scan first, then clean explicitly:

mcp-cleanup scan
mcp-cleanup clean
mcp-cleanup clean --apply

• scan shows MCP-related process residue.
• clean is a dry run and prints the exact targets.
• clean --apply sends SIGTERM to detected Codex STDIO MCP root processes.
• --force upgrades cleanup to SIGKILL.

Commands

Command	Purpose
mcp-cleanup scan	Show Codex STDIO MCP residue and local HTTP MCP services.
mcp-cleanup scan --json	Print machine-readable scan output.
mcp-cleanup clean	Dry-run cleanup and show targets.
mcp-cleanup clean --apply	Clean detected Codex STDIO MCP root processes.
mcp-cleanup clean --name codegraph --apply	Clean only one MCP family.
mcp-cleanup install-hook --apply	Install the Codex hook for deferred cleanup.
mcp-cleanup zombies scan	Optional system zombie diagnostics.

Codex Hook

Install the Codex hook with one command:

mcp-cleanup install-hook --apply

It writes or merges ~/.codex/hooks.json, backs up an existing file before changing it, and does not duplicate the hook if you run it again.

Codex Stop hooks run at turn scope, not app-window-exit scope. For that reason the installed hook does not directly kill MCP processes on every Stop. Instead, it installs a deferred watcher:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "mcp-cleanup hook --apply --codex-stop-json",
            "timeout": 5,
            "statusMessage": "Scheduling MCP cleanup"
          }
        ]
      }
    ]
  }
}

mcp-cleanup hook --apply --codex-stop-json starts a detached watcher and prints the empty JSON object Codex expects from a successful Stop hook. The watcher waits for the Codex parent process to exit, then runs the same cleanup behavior as mcp-cleanup clean --apply.

For manual debugging, you can omit --codex-stop-json to see a human-readable report:

mcp-cleanup hook --apply

After editing hooks, Codex may ask you to review and trust the command through /hooks.

What It Cleans

By default, cleanup targets only Codex STDIO MCP root processes:

• codegraph serve --mcp
• apifox-mcp-server
• Codex node_repl

Local HTTP MCP services are reported but skipped by default. For example, a service such as xiaocan may show as 1 service, 6 processes because it is started through a shell/package-manager/watch chain. That is still one HTTP service, and ordinary cleanup will not kill it.

Safety Model

• Read-only by default.
• scan never kills processes.
• clean is a dry run unless --apply is present.
• SIGKILL requires --force.
• Local HTTP MCP services are skipped by default.
• System zombie processes are not shown in the default scan.

System Zombies

A Z or <defunct> process has already exited. Killing the child PID cannot clear it. The parent process must reap it, or the parent app must be restarted.

System zombie diagnostics are intentionally separate from normal MCP cleanup:

mcp-cleanup zombies scan
mcp-cleanup zombies clean --parent <pid>
mcp-cleanup zombies clean --parent <pid> --apply

Use this only when you explicitly want to inspect or signal the parent app. Normal mcp-cleanup scan and mcp-cleanup clean --apply will not show or touch unrelated apps.

Development

npm test
npm run pack:check
node src/cli.js scan

This package has no runtime dependencies and uses Node.js built-ins only.