HasanJahidul/localhost-mcp
📇 🏠 🍎 🪟 🐧 - Inspect, manage, and kill local dev servers. Lists what's listening on each port (pid, framework, project, uptime, memory, cpu), diagnoses port conflicts with free alternatives nearby, finds zombie processes, and kills by pid or port with a dry-run default.
Quick Install
{
"mcpServers": {
"hasanjahidul-localhost-mcp": {
"command": "npx",
"args": [
"-y",
"hasanjahidul-localhost-mcp"
]
}
}
}Using an AI coding agent (Claude Code, Cursor, etc.)? Copy a ready-made prompt that tells it to fetch the setup instructions and install this server for you.
Documentation Overview
localhost-mcp
MCP server that inspects, manages, and kills local dev servers. Stop guessing what's on :3000.
Pairs with terminal-history-mcp — together they give your AI agent full memory of your dev environment: what you ran, what's running.
Why
Every dev hits these daily:
Error: listen EADDRINUSE :::3000— what's holding the port?- 5 forgotten
node/vite/nextPIDs from last week eating RAM - Switching projects → no idea which dev servers still running
lsof -i :3000,kill -9 <pid>, repeat
localhost-mcp makes it one tool call.
Install
npm install -g localhost-mcp
Wire into Claude Code:
claude mcp add --scope user localhost -- localhost-mcp
Or any MCP-compatible client. The command runs as a stdio MCP server.
Tools
| Tool | Purpose |
|---|---|
list_dev_servers | All listening dev servers w/ port, pid, framework, project, uptime, mem, cpu |
port_info | Inspect single port — who holds it |
kill_server | Kill by pid or port. Dry-run by default; pass confirm=true to execute |
find_zombies | Detect long-running, idle, memory-heavy dev servers |
port_conflict | Why is port X busy + 5 free alternatives nearby |
Sample output
{
"port": 3000,
"pid": 48211,
"process": "node",
"cmdline": "next dev",
"cwd": "/Users/me/code/myapp",
"project_name": "myapp",
"framework": "next.js",
"uptime_seconds": 14523,
"memory_mb": 412,
"cpu_pct": 0.3,
"user": "me"
}
Safety
kill_serverdefaults to dry-run. Must passconfirm=true.- Refuses to kill PIDs < 1000 (system processes).
- Refuses processes outside the dev whitelist (node, python, ruby, go, deno, bun, php, java, rails, vite, next, etc).
- SIGTERM first, escalates to SIGKILL after 5s timeout.
Frameworks detected
next.js, vite, nuxt, remix, astro, webpack-dev-server, esbuild, create-react-app, express, fastify, koa, hono, rails, django, flask, fastapi, uvicorn, gunicorn, deno, bun, php-builtin, jekyll, hugo.
Falls back to package.json sniffing when the cmdline is generic (node server.js).
Platform support
- macOS — full support (uses
lsof) - Linux — full support (uses
lsof+/proc) - Windows — basic port scan only (uses
netstat); cwd / framework detection limited
CLI usage
localhost-mcp list # JSON list of all dev servers
localhost-mcp zombies # JSON list of zombie candidates
localhost-mcp # Start MCP stdio server
Build from source
git clone https://github.com/hasanjahidul/localhost-mcp.git
cd localhost-mcp
npm install
npm run build
node dist/cli.js list
License
MIT