Ports + MCP
A focused macOS utility and MCP server for inspecting and safely resolving local port conflicts.
Finding which process holds a local port, and safely killing it, usually means piecing together lsof and ps by hand — slow and error-prone, especially for AI agents that need to resolve port conflicts programmatically.
Listening on stdio Initialized Ports MCP Server Registered tools: list_ports, inspect_port, kill_process
Overview
A macOS-only local tool for listing listening TCP ports and the processes behind them, exposed both as an MCP stdio server for AI agents and as a small local web UI for manual use.
The need
Debugging “port already in use” errors on a dev machine usually means manually running lsof and ps, then deciding whether it’s safe to kill the process. AI coding agents hit the same problem but have no safe, structured way to do it.
Product goals
- Give agents and developers a read-only way to list ports and owning processes first.
- Make killing a process an explicit, guarded action rather than a silent side effect.
Constraints
- macOS only, relies on
lsof/ps. - Local-only — not intended for production or remote/multi-user use.
- Solo project, prototype stage.
The solution
An MCP server exposing list_ports, find_process_by_port, and a guarded kill_process_on_port (dry-run by default, requires explicit confirmation and re-validates the PID still owns the port before signaling). An arbitrary shell-based restart path from an earlier version was removed for safety.
Product experience
Command-line / MCP tool — no visual product surface beyond the small local web UI.
The process
Built solo as a focused utility; safety guards (dry-run defaults, PID re-validation) were added deliberately after the initial version.
AI-assisted workflow
Built with AI-assisted coding, with particular attention paid to hardening the destructive kill_process_on_port path by hand.
Current state
Prototype — functional, used locally, not yet broadly adopted.
What is next
No committed roadmap; revisited as local port-conflict friction comes up.
Lessons learned
Read-only inspection first, destructive actions guarded and explicit second — a pattern worth carrying into other agent-facing tools.
Current Reality
- ·macOS binary release available via GitHub Releases.
- ·MCP stdio server interface compatible with Claude and Antigravity.
- ·Cross-platform support for Linux / Windows process inspection.