Localhost Mcp

by HasanJahidul

3 stars

382 downloads

Not rated

GitHub

Other

About

MCP server: inspect, manage, kill local dev servers. Stop guessing what's on :3000.

Details

Author: HasanJahidul
GitHub stars: 3
Downloads: 382
Categories: Other

- Lists all listening dev servers with port, PID, framework, project, uptime, memory, CPU
- Inspects a single port to identify the holding process
- Kills servers by PID or port, with dry‑run mode by default
- Detects zombie dev servers (long‑running, idle, memory‑heavy)
- Identifies port conflicts and suggests five free nearby ports
- Refuses to kill system processes (PIDs < 1000) and non‑whitelisted executables

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Localhost Mcp

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

From the repository

Install globally with npm install -g localhost-mcp, then wire into Claude Code with claude mcp add --scope user localhost -- localhost-mcp or any MCP-compatible client. The server operates as a stdio MCP server. CLI usage includes localhost-mcp list (list dev servers), localhost-mcp zombies (find zombie candidates), and plain localhost-mcp to start the stdio server.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "localhost mcp": {
            "localhost": {
                "command": "npx",
                "args": [
                    "-y",
                    "localhost-mcp"
                ]
            }
        }
    }
}

McpServers

{
    "localhost": {
        "command": "npx",
        "args": [
            "-y",
            "localhost-mcp"
        ]
    }
}

localhost-mcp

MCP server that inspects, manages, and kills local dev servers. Stop guessing what's on :3000.

demo

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 / next PIDs 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_server defaults to dry-run. Must pass confirm=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

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

localhost-mcp

Why

Install

Tools

Sample output

Safety

Frameworks detected

Platform support

CLI usage

Build from source

License

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀