Localhost MCP

What HasanJahidul/localhost-mcp MCP server does

HasanJahidul/localhost-mcp MCP server exposes local development-server inspection and process-management operations through MCP. It is intended for diagnosing issues such as an occupied port, forgotten development processes, or uncertainty about which project owns a running server.

The server can enumerate listening development servers and report their port, PID, process name, command line, working directory, project name, detected framework, uptime, memory use, CPU use, and user. It can also inspect one port, locate likely zombie processes, and explain why a port is unavailable while suggesting five nearby free ports.

Supported framework detection includes 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’s built-in server, Jekyll, and Hugo. When the command line is generic, the project’s package.json is used as a fallback signal.

How it works

HasanJahidul/localhost-mcp MCP server runs as a local stdio MCP server. On macOS it uses lsof for full support. Linux uses lsof and /proc; Windows support is limited to basic port scanning through netstat, so working-directory and framework details may be incomplete.

The included command-line interface can emit JSON for a complete server list or zombie candidates. Running localhost-mcp without a subcommand starts the MCP stdio server. The repository also notes that it can be paired with terminal-history-mcp, although that is a separate project rather than a dependency described here.

Setup and configuration

Install the npm package globally:

npm install -g localhost-mcp

For Claude Code, register the executable with:

claude mcp add --scope user localhost -- localhost-mcp

The README states that the command can also be used with other MCP-compatible clients. No environment variables, API credentials, or hosted service configuration are documented. To build from source, clone the repository, run npm install, run npm run build, and use node dist/cli.js list for a JSON listing.

Tools and capabilities

HasanJahidul/localhost-mcp MCP server provides these operations:

• list_dev_servers: Lists detected development servers and their process and resource details.
• port_info: Identifies the process holding a selected port.
• kill_server: Targets a server by PID or port.
• find_zombies: Finds long-running, idle, or memory-heavy development servers.
• port_conflict: Explains a busy port and returns five nearby alternatives.

The command-line equivalents include localhost-mcp list and localhost-mcp zombies.

Limitations and notes

Killing is conservative by design. kill_server previews the action unless confirm=true is supplied, refuses PIDs below 1000, and only permits processes from a development whitelist. It sends SIGTERM first and escalates to SIGKILL after five seconds.

Windows provides only basic port scanning, with limited framework and current-working-directory detection. The server focuses on local development processes rather than general system-process management.