Skip to main content
Glama
localhost-mcp

localhost-mcp

by HasanJahidul

localhost-mcp

用于检查、管理和终止本地开发服务器的 MCP 服务器。无需再猜测 :3000 上运行的是什么。

demo

与 terminal-history-mcp 配合使用——它们共同为您的 AI 代理提供完整的开发环境记忆:您运行了什么,以及正在运行什么。

为什么使用它

每位开发者每天都会遇到这些问题:

  • Error: listen EADDRINUSE :::3000 — 到底是什么占用了端口?

  • 上周遗留的 5 个 node / vite / next 进程正在占用内存

  • 切换项目时 → 不知道哪些开发服务器仍在运行

  • lsof -i :3000,kill -9 <pid>,重复操作

localhost-mcp 让这一切只需一次工具调用即可解决。

Related MCP server: Git Insight MCP

安装

npm install -g localhost-mcp

将其接入 Claude Code:

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

或任何兼容 MCP 的客户端。该命令作为 stdio MCP 服务器运行。

工具

工具

用途

list_dev_servers

列出所有正在监听的开发服务器,包含端口、PID、框架、项目、运行时间、内存、CPU

port_info

检查单个端口 — 谁占用了它

kill_server

按 PID 或端口终止进程。默认进行试运行;传入 confirm=true 以执行

find_zombies

检测长时间运行、空闲、内存占用过高的开发服务器

port_conflict

为什么端口 X 被占用 + 附近 5 个可用的替代端口

示例输出

{
  "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"
}

安全性

  • kill_server 默认为试运行模式。必须传入 confirm=true。

  • 拒绝终止 PID < 1000 的进程(系统进程)。

  • 拒绝终止开发白名单之外的进程(node, python, ruby, go, deno, bun, php, java, rails, vite, next 等)。

  • 先发送 SIGTERM,5 秒超时后升级为 SIGKILL。

支持的框架检测

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。

当命令行通用(如 node server.js)时,会回退到 package.json 嗅探。

平台支持

  • macOS — 完全支持(使用 lsof)

  • Linux — 完全支持(使用 lsof + /proc)

  • Windows — 仅基础端口扫描(使用 netstat);当前工作目录 / 框架检测受限

CLI 使用

localhost-mcp list      # JSON list of all dev servers
localhost-mcp zombies   # JSON list of zombie candidates
localhost-mcp           # Start MCP stdio server

从源码构建

git clone https://github.com/hasanjahidul/localhost-mcp.git
cd localhost-mcp
npm install
npm run build
node dist/cli.js list

许可证

MIT

Available Tools

5 tools
find_zombiesA
Read-onlyIdempotent

Read-only. Flags dev servers that look abandoned — all three of: uptime > 6h AND CPU < 1% AND memory > 100MB. By default it excludes known always-on noise (VS Code server, language servers, other MCP servers, postgres/redis, sidekiq, etc.); set include_excluded: true to also list those. Each candidate comes with the reasons it matched. This tool never kills anything — pass results to kill_server. Returns { count, candidates[] }.

Inputs: include_excluded. Returns: count, candidates

kill_serverA
Destructive

Terminates a local dev server by pid or port. DESTRUCTIVE. Safe by default: with no confirm, this is a DRY RUN — it reports what it would kill and changes nothing. Pass confirm: true to actually terminate: sends SIGTERM, waits up to 5s, then escalates to SIGKILL (or SIGKILL immediately if force: true). Refuses PIDs below 1000 and processes that don't look like dev servers. Provide exactly one of pid or port. Returns what was (or would be) killed and the signal used.

Inputs: pid, port, force, confirm. Returns: pid, port, killed, signal, +3 more

list_dev_serversA
Read-onlyIdempotent

Read-only. Lists every local development server (next, vite, nuxt, remix, astro, rails, django, flask, express, deno, bun, etc.) currently LISTENING on a TCP port. For each: port, pid, process name, command line, working directory, project name, detected framework, uptime, memory (MB), CPU %, and owning user. Uses lsof on macOS/Linux and netstat on Windows; on Windows the cwd/framework fields are limited. Takes no arguments. Returns { count, servers[] }.

Inputs: no named parameters. Returns: count, servers

port_conflictA
Read-onlyIdempotent

Read-only. Diagnoses an EADDRINUSE situation: given a port, returns the dev server currently blocking it plus 5 free alternative ports nearby. Use it when a listen EADDRINUSE error fires and you want both the culprit and a port to switch to.

Inputs: port (required). Returns: port, blocked_by, alternatives

port_infoA
Read-onlyIdempotent

Read-only. Inspects a single TCP port and reports the dev server holding it (same fields as list_dev_servers). If nothing is listening, or the listener is not a recognised dev process, returns { port, status: "free" }. Useful for answering "what's on :3000?" before starting or killing something.

Inputs: port (required). Returns: Either a dev-server record (see list_dev_servers) or `{ port, status: "free" }`.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing servers, inspecting a single port, finding zombies, killing servers, and diagnosing port conflicts. There is no functional overlap.

    Naming Consistency4/5

    Tool names use snake_case, and most follow a verb_noun pattern (find_zombies, kill_server, list_dev_servers). However, port_conflict and port_info are noun-first, which is a minor inconsistency.

    Tool Count5/5

    With 5 tools, the set is well-scoped for managing local dev servers: query, inspect, cleanup, and conflict resolution. No tool feels superfluous or missing.

    Completeness4/5

    The tools cover listing, inspecting, zombie identification, killing, and conflict diagnosis. There is a minor gap in that bulk operations (e.g., kill all zombies) are not directly supported, but the intended workflow is clear.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Developers: Search your zsh, bash, or fish shell history from Claude Code, Cline, Cursor, Zed, or any MCP client using tools like search_history (full-text with timestamp/CWD/exit code), recent_in_dir, failed_commands, and command_chains for multi-step sequences. Reindex after new activity. Local-only SQLite FTS5 with secrets redacted before storage.
      7
      38 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      See and control the local dev servers your coding agents leave running. Lists listeners with provenance — which agent, terminal and git worktree started each — kills strays, and allocates collision-free ports so parallel agents stop fighting over :3000.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for managing local dev ports on macOS. It enables AI agents to inspect listening ports, identify owning processes and parent chains, kill processes safely, wait for ports, and report LAN exposure.
      7 npm
      1
      MIT