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 PID가 RAM을 점유 중

  • 프로젝트 전환 시 어떤 개발 서버가 여전히 실행 중인지 알 수 없음

  • 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 또는 포트로 종료. 기본적으로 드라이런(dry-run) 실행; 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는 기본적으로 드라이런(dry-run)입니다. confirm=true를 전달해야 합니다.

  • 1000 미만의 PID(시스템 프로세스)는 종료를 거부합니다.

  • 개발 화이트리스트(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 사용); cwd / 프레임워크 감지 제한적

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
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      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
      149 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.
      8 npm
      1
      MIT