Skip to content

AI assistants (MCP)

portcheck mcp runs portcheck as a Model Context Protocol server, so AI coding assistants can see what's using a port and fix it themselves. When npm run dev fails with EADDRINUSE in an agent session, the assistant checks which process holds the port, tells you who started it, and stops it if you agree, or picks a free port instead.

You:        npm run dev fails, port 3000 is in use. Fix it.
Assistant:  [check_port 3000] Port 3000 is held by node (pid 41852), started by
            npm ← zsh 2 hours ago: an older dev server. Stop it?
You:        yes
Assistant:  [stop_process port 3000] Stopped node (pid 41852). [npm run dev] Running
            on http://localhost:3000.

Tools

Tool What it does
check_port Whether ports are free; for each port in use, the process, PID, user, command, who started it, or the container
list_ports Every listening port, filterable by port range, process name or protocol
find_free_port Free ports, optionally in a range
wait_for_port Waits until a server accepts connections (or, with free, until a port is free)
stop_process Stops what listens on a port, or a PID; dry_run reports what it would stop

Each tool returns the same JSON as the matching --json command. stop_process is marked destructive, so assistants ask before using it, and it keeps kill's safety guards: it never stops system processes or the assistant itself, and ports published by Docker, Podman or WSL get the right stop command instead.

Set up

Install portcheck first, then add it to your assistant. If your assistant can't find portcheck, use its full path (which portcheck).

No install: run it through npx

With Node.js, any assistant can run portcheck without installing it: use "command": "npx", "args": ["-y", "portcheck-cli", "mcp"]. In Claude Code: claude mcp add --scope user portcheck -- npx -y portcheck-cli mcp.

claude mcp add --scope user portcheck -- portcheck mcp

code --add-mcp '{"name":"portcheck","command":"portcheck","args":["mcp"]}'

or in .vscode/mcp.json:

{ "servers": { "portcheck": { "type": "stdio", "command": "portcheck", "args": ["mcp"] } } }

In ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{ "mcpServers": { "portcheck": { "command": "portcheck", "args": ["mcp"] } } }

In ~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "portcheck": { "command": "portcheck", "args": ["mcp"] } } }

In Settings → Developer → Edit Config (claude_desktop_config.json), with the full path, since desktop apps don't see your shell's PATH:

{ "mcpServers": { "portcheck": { "command": "/opt/homebrew/bin/portcheck", "args": ["mcp"] } } }

Install the Portcheck extension (Extensions → search "portcheck"). Or, in the Agent Panel's settings, Add Custom Server with the command portcheck mcp.

In ~/.codex/config.toml:

[mcp_servers.portcheck]
command = "portcheck"
args = ["mcp"]

Other MCP clients work the same way: a stdio server started with portcheck mcp.