Browser extension for Brave that shows which process serves a localhost tab, indicates when nothing is listening, and lets users stop the process from the popup.
Detects ports published by Docker containers, shows the container or distro, and advises stopping it in Docker rather than killing the port-forwarding proxy.
JetBrains plugin support for GoLand: detects port conflicts in run configurations, names the process, offers stop-and-rerun, and lists listening ports in a Ports tool window.
JetBrains plugin support for IntelliJ IDEA: detects port conflicts in run configurations, names the process, offers stop-and-rerun, and lists listening ports in a Ports tool window.
Provides a JetBrains IDE plugin that turns port-in-use run failures into a "Stop it and rerun" action and adds a Ports tool window listing listening ports.
Provides a Neovim plugin with a :Portcheck picker to check, kill, and free ports, and to stop processes holding ports used in :terminal.
Detects ports published by Podman containers, shows the container details, and advises stopping it in Podman rather than killing the port-forwarding proxy.
JetBrains plugin support for PyCharm: detects port conflicts in run configurations, names the process, offers stop-and-rerun, and lists listening ports in a Ports tool window.
Provides Raycast commands to search listening ports, check a port, kill a port, and find free ports from the macOS launcher.
VS Code-compatible extension available via Open VSX for VSCodium that turns "port in use" terminal errors into one-click fixes and lists listening ports in a sidebar.
JetBrains plugin support for WebStorm: detects port conflicts in run configurations, names the process, offers stop-and-rerun, and lists listening ports in a Ports tool window.
npx portcheck-cli kill 3000portcheck 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
Related MCP server: tidyports
Command | ||
🔍 |
| Every listening socket with its process, PID and user |
✅ |
| Is the port free? If not, who holds it? Exit code 0 or 1 for scripts |
🆓 |
| Free ports, verified by actually binding them |
🛑 |
| Graceful SIGTERM, then SIGKILL; refuses PID 1, your shell and system processes |
📡 |
| Rate-limited TCP connect checks of remote hosts. No root needed |
⏳ |
| Block until services accept connections, or until a port is free. Built for CI |
▶️ |
| Start a command on a free port ( |
🩺 |
| Check the ports listed in |
🖥️ |
| Live, sortable, filterable TUI. Stop processes without leaving it |
🌐 | Edge (and Chrome): which process serves a localhost tab, | |
🧩 | "Port in use" errors in the terminal become one-click fixes; listening ports in the sidebar (guide) | |
🤖 |
| AI assistants (Claude Code, Cursor, Copilot…) check and free ports themselves (guide) |
⌨️ | Search Ports, Check Port, Kill Port and Find Free Port from the Mac launcher | |
✍️ |
| |
🔌 | Your listening ports in the macOS menu bar or Windows/Linux tray: stop, open, copy in two clicks | |
🧠 | IntelliJ IDEA, WebStorm, PyCharm, GoLand…: "port in use" in Run/Debug → Stop it and rerun; a Ports tool window |
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).
Same commands and output on every OS. It replaces lsof -i, netstat -ano, ss -ltnp and kill.
Built for scripts. --json follows a versioned schema, exit codes are stable, and results go to stdout while messages go to stderr.
Container- and WSL-aware. Ports published by Docker/Podman or forwarded from WSL show the container or distro, and kill tells you how to stop it there instead of killing the proxy.
Honest about permissions. Hidden owners are shown as hidden, with a hint on how to see them.
A Go library too. See pkg/.
# 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-bucket
scoop install portcheck
# npm (any OS): run it without installing
npx portcheck-cli 3000
# PyPI (any OS)
pipx install portcheck-tool
# Go 1.26+
go install github.com/roystondwork-dev/portcheck/cmd/portcheck@latest.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.
$ portcheck 3000
PORT PROTO STATUS PID PROCESS USER
3000 tcp in-use 42379 node alice
$ portcheck kill 3000
About to terminate:
PID 42379 node (port 3000)
Proceed? [y/N] y
PID PROCESS RESULT DETAIL
42379 node terminated
$ portcheck free 3000-3999 -n 2 -o plain
PORT
3000
3001
$ portcheck list -l --json | jq '.data.sockets[] | {port: .localPort, name: .process.name}'📖 Documentation: https://roystondwork-dev.github.io/portcheck/ (quickstart · guides · CLI reference · permissions by OS · FAQ)
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)
}
}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
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.
| Name | Required | Description | Default |
|---|---|---|---|
| ports | Yes | the ports to check, e.g. [3000] | |
| proto | No | tcp (default) or udp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe read-only, idempotent, local-only profile, and the description adds real value beyond them: it specifies exactly what is returned per in-use port, including the container publisher when Docker or Podman is involved. It does not cover behavior for free ports or any output shape, but with no output schema the process-attribution detail is the load-bearing information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what it does, what it returns, and when to reach for it. The trigger condition is front-loaded at the end as a decisive call to action with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only annotations for safety metadata, the description carries the return-value burden and does so well by enumerating the per-port diagnostic fields. The one gap is that it never explains what the result looks like for a free port or references the TCP/UDP dimension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema and the baseline applies. The description adds nothing about the proto parameter (tcp/udp default) or the array-of-ports input beyond the plural 'ports', so it neither compensates nor detracts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (check ports, report the owning process with name, PID, user, command line, and container). That process-attribution detail implicitly separates it from find_free_port and list_ports, but the description never names those siblings, so the differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete trigger: 'Use it first when a server fails with "address already in use" or EADDRINUSE.' That is a clear when-to-use signal. It stops short of routing the agent elsewhere — nothing says to use find_free_port when you want an available port or list_ports for enumeration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | how many free ports (default 1) | |
| range | No | where to look, e.g. 3000-3999 (default: from 1024 up) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered elsewhere. The description adds genuinely new behavioural context that annotations cannot express: results are verified by actually binding the port, which explains trustworthiness and hints at the momentary side effect of the check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, zero filler, and the core capability plus its verification guarantee are front-loaded before the usage hint. Nothing is repeated needlessly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-optional-parameter read tool with full schema coverage and clear annotations, the description covers what it does, how it verifies, and when to reach for it. The only omission is any indication of the return shape (a list of port numbers, presumably) since no output schema exists, which would be a small but useful addition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters and their defaults (count=1, range from 1024 up) are already documented in the schema. The description's '(e.g. 3000-3999)' restates the schema's own example and adds no new syntax, validation or edge-case meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('find ports that are free right now') plus the verification method ('verified by binding them'), which makes the result meaningful. It implicitly separates itself from check_port (one known port) and list_ports (enumeration), but never names a sibling explicitly, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use it to start a server on another port instead of stopping what holds one" gives a concrete scenario and implicitly frames the alternative behaviour (stop_process) it is meant to replace. There are no explicit when-not conditions or rate/permission caveats, but the primary use case is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | only processes whose name matches this glob, e.g. node* | |
| ports | No | only these local ports, e.g. 3000 or 3000-3010,8080 | |
| proto | No | tcp or udp (default both) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the returned fields (process, PID, user, launcher chain like 'npm ← zsh', container name) and that Docker/Podman-published ports are included — context an agent cannot get from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler: the first defines the output payload, the second routes usage. The output detail is front-loaded where it matters most, and no sentence merely restates the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by enumerating the returned fields and noting container coverage. With all three parameters fully documented in the schema and a safe read-only annotation set, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns a bump by tying name to a concrete glob example ('node*') and ports to a range form, framing both as discovery aids. It adds nothing for proto, which the schema already documents as 'tcp or udp (default both)'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb (List) plus resource (ports listening on this machine) with an explicit inventory of what each entry contains: process, PID, user, parent shell, and container. It never names the sibling tools (check_port, find_free_port, wait_for_port), so differentiation is inferred from the word 'List' rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives two concrete use cases: 'see what's running' and 'find a dev server by name (name="node*") or port range', which maps directly onto the name and ports parameters. It stops short of exclusions, e.g. it never says to use check_port for a single known port or find_free_port when you need an available port.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | No | stop this process | |
| port | No | stop what listens on this port | |
| force | No | kill at once instead of asking it to exit first | |
| dry_run | No | only report what would be stopped |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the destructiveHint annotation: a two-phase termination (graceful request, then kill after 5 s), a self-protection guard, and the notable edge case that Docker/Podman/WSL-published ports return a command to run instead of being killed. That last detail materially changes what the agent should expect on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core action and target options, then escalation, refusals, container caveat, and safety workflow. No filler and no repetition of the annotation fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description covers most of what matters for a destructive tool: escalation, refusal conditions, and the notable container case. It does not describe the return payload for a successful stop (e.g., PID/process name reported), which is the only real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds the escalation timing behind `force` (5 s grace period) and frames `dry_run` as a preview workflow, which the schema only states as 'only report what would be stopped'. Small but genuine added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (stop) and resource (a process), plus the two ways to target it (port or PID). This is clearly distinct from the read-only siblings like list_ports and check_port, which the description positions as a prior inspection step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit workflow guidance: use dry_run to preview what would be stopped, and run check_port first to identify the process before stopping it. It also states hard exclusions (system processes and the assistant itself are refused), so the agent knows when this call will decline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| free | No | wait until the port is free instead of open | |
| host | No | host (default localhost) | |
| port | Yes | the port to wait for | |
| timeout_seconds | No | give up after this many seconds (default 30, at most 300) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail: it returns as soon as the port is ready and fails after timeout_seconds. It does not describe polling behavior or failure formatting, but that is a minor gap given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with no filler. It front-loads the core behavior and then adds the free-port alternative and timeout failure semantics. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple four-parameter tool with full schema coverage and no output schema, the description is complete enough to call correctly. It explains the main mode, the free=true mode, the waiting behavior, and timeout failure. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented in the input schema. The description reinforces the meaning of free=true and timeout_seconds, but adds little beyond what the schema provides and does not mention host. This meets the baseline for fully covered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: waiting for a port to accept connections or, with free=true, to become free. It clearly distinguishes the waiting behavior from a simple check, though it does not explicitly name sibling tools such as check_port. The purpose is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage contexts, such as waiting for a server or database to finish starting, and explains the free=true alternative. It also states that the tool fails after timeout_seconds. It does not explicitly compare against check_port or find_free_port, but the intended usage is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1check_port2 fields changedInput schema / properties / ports / minItemsAdded value: +1Input schema / properties / ports / typePrevious value: -[
- "null",
- "array"
-]New value: +"array"v0.1.0check_portfind_free_portlist_portsstop_processwait_for_portScored across 5 tools
Each tool has a distinct role: check_port checks specific ports and explains holders, list_ports enumerates listening ports, find_free_port locates available ports, stop_process terminates a holder, and wait_for_port blocks until readiness. check_port and list_ports overlap in reporting process details, but their usage guidance (specific ports vs. inventory/search) keeps them separable.
All names are snake_case with a leading action verb: check_port, find_free_port, list_ports, stop_process, wait_for_port. Minor variation in verb phrasing (find_free_port, wait_for_port) is natural and consistent, not mixed conventions.
Five tools is well-scoped for a port diagnostics utility, with each covering a distinct phase: check, discover, inventory, stop, and wait. There are no redundant or filler tools.
The set covers the core lifecycle for port troubleshooting: detect conflicts, identify holders, find free alternatives, stop processes safely, and wait for readiness. No obvious operational gap remains for the stated purpose.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Publishes what an AI made — a page, a markdown or PDF doc, or a whole site — to a live HTTPS link. Runs locally over stdio from the @drop2run/mcp npm package, or hosted at https://mcp.dropto.run/mcp for chats that connect by URL.
