io.github.roystondwork-devPublished by GitHub account roystondwork-devv0.11.0Updated Oct 27, 2026
See which process holds a port, find free ports, and stop a dev server safely.
Local MCP server that lets an assistant inspect which process holds a TCP/UDP port, find free ports, wait for services, and stop dev servers safely.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
See what's using your ports, find free ones, free them up, and check remote hosts.
One static binary for macOS, Linux and Windows.
[CI] [CodeQL] [Coverage] [Release] [OpenSSF Scorecard] [OpenSSF Best Practices] [M8ven Score] [Go Reference] [License: MIT]
portcheck shows what holds the port and who started it, asks, then stops it gently
(and never touches system processes). It's a safer kill-port, with
nothing to install first.
Fixes for the error you're seeing: Node.js, Next.js, Vite · Python, Django, Flask · Docker · Rails, Spring Boot, Go, .NET, PHP · macOS · Windows · Linux
When a dev server fails because its port is taken, the extension says who holds it and fixes it: stop it and re-run, or re-run on the next free port.
Install Portcheck - Port in Use Fixer from the VS Code Marketplace (search "portcheck" in VS Code) or Open VSX (VSCodium, Cursor, Windsurf). portcheck is built in.
In IntelliJ IDEA, WebStorm, PyCharm, GoLand and the other JetBrains IDEs, when a run configuration fails because its port is taken, a notification names the process and offers Stop it and rerun; the Ports tool window lists every listening port.
Install portcheck-jetbrains-<version>.zip from the
latest release
(Settings → Plugins → ⚙ → Install Plugin from Disk…); it is in review on JetBrains Marketplace
(guide).
On every localhost tab, a badge names the process serving it, or says off when nothing
is listening; the popup shows who started it and stops it safely.
Install Portcheck - Localhost Port Inspector from
Microsoft Edge Add-ons, then run portcheck browser install once.
For Chrome, Brave and Chromium, load the zip from the
latest release
(guide).
lsof -i, netstat -ano, ss -ltnp and kill.--json follows a versioned schema, exit codes are stable, and results go to stdout while messages go to stderr.kill tells you how to stop it there instead of killing the proxy.pkg/..deb, .rpm, .apk and archives for amd64/arm64 are on the
releases page. The
checksum file covering every artifact is signed with cosign (keyless), and
releases ship SBOMs and SLSA provenance; see
verifying downloads.
📖 Documentation: https://roystondwork-dev.github.io/portcheck/ (quickstart · guides · CLI reference · permissions by OS · FAQ)
See the library guide for portspec, inspect, freeport, killer, scan, waitfor and containers.
portcheck scan makes ordinary TCP connections and has no stealth features. Only
scan hosts and networks you own or are authorized to test.
Contributions are welcome! See CONTRIBUTING.md for setup and standards (every change is tested on Linux, macOS and Windows, with a 100% coverage gate on the library), and TASKS.md for the roadmap and status. Please follow the Code of Conduct, and report vulnerabilities privately as described in SECURITY.md.
MIT © 2026 Royston D and portcheck contributors
Source: README.md at commit 0b8f56f
Check a port
Check whether ports are free. For each port in use, says which process holds it: name, PID, user, command line, who started it, and the container if Docker or Podman publishes it. Use it first when a server fails with "address already in use" or EADDRINUSE.
portsrequiredprotoFind free ports
Find ports that are free right now, verified by binding them, optionally within a range (e.g. 3000-3999). Use it to start a server on another port instead of stopping what holds one.
countrangeList listening ports
List the ports listening on this machine, with the process, PID, user and who started it (e.g. npm ← zsh), and the container for ports published by Docker or Podman. Use it to see what's running, or to find a dev server by name (name="node*") or port range.
nameportsprotoStop a process
Stop the process listening on a port, or a process by PID: asks it to exit, then kills it after 5 s. Refuses system processes and the assistant itself. Ports published by Docker, Podman or WSL report the command to run instead. Use dry_run to see what would be stopped, and check_port first to tell the user what it is.
pidportforcedry_runWait for a port
Wait until a port accepts connections, e.g. until a server or database has finished starting, or with free=true until a port is free again. Returns as soon as it's ready, or fails after timeout_seconds.
freehostportrequiredtimeout_seconds90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
npx portcheck-cli kill 3000# Homebrew (macOS, Linux)brew install roystondwork-dev/tap/portcheck
# winget (Windows; the package is waiting for Microsoft's review)winget install roystondwork-dev.portcheck
# Scoop (Windows)scoop bucket add portcheck https://github.com/roystondwork-dev/scoop-bucketscoop install portcheck
# npm (any OS): run it without installingnpx portcheck-cli 3000
# PyPI (any OS)pipx install portcheck-tool
# Go 1.26+go install github.com/roystondwork-dev/portcheck/cmd/portcheck@latest$ portcheck 3000PORT PROTO STATUS PID PROCESS USER3000 tcp in-use 42379 node alice
$ portcheck kill 3000About to terminate: PID 42379 node (port 3000)Proceed? [y/N] yPID PROCESS RESULT DETAIL42379 node terminated
$ portcheck free 3000-3999 -n 2 -o plainPORT30003001
$ portcheck list -l --json | jq '.data.sockets[] | {port: .localPort, name: .process.name}'res, err := inspect.NewSystem().List(ctx, inspect.Filter{Ports: portspec.Single(3000), ListeningOnly: true})if err != nil { log.Fatal(err)}for _, s := range res.Sockets { if s.Process != nil { // nil when the owner is hidden from your user fmt.Println(s.PID, s.Process.Name) }}