Localhost Mcp

localhost-mcp

用于检查、管理和终止本地开发服务的 MCP 服务。不必再猜 :3000 上运行着什么。

可与 terminal-history-mcp 配合使用——二者共同为你的 AI Agent 提供开发环境的完整记忆：你运行过什么、当前正在运行什么。

为什么需要

每个开发者每天都会遇到这些问题：

• Error: listen EADDRINUSE :::3000——是什么占用了这个端口？
• 上周遗忘的 5 个 node / vite / next 进程 PID 正在占用内存
• 切换项目后，不知道还有哪些开发服务在运行
• lsof -i :3000、kill -9 <pid>，反复折腾

localhost-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