kill-port-mcp

中文 | English

中文文档

跨平台进程与端口管理 MCP 服务，支持 Windows / macOS / Linux。

帮助 AI 在重新运行项目前关闭占用端口的进程，避免端口冲突。

功能概览（11 个 Tools）

| Tool | 类型 | 说明 | |---|---|---| | list_listening_ports | 查询 | 列出所有正在监听的端口及对应进程（含内存占用） | | find_by_port | 查询 | 查找占用指定端口的进程详情（含内存、命令行） | | find_by_port_range | 查询 | 查找端口范围内所有被占用的端口 | | check_port | 查询 | 检查单个端口是否可用（含超时保护） | | check_port_range | 查询 | 批量检查端口范围可用性（返回可用/占用列表） | | get_system_info | 查询 | 获取操作系统、CPU、内存等系统信息 | | kill_by_port | 操作 | 关闭指定端口的所有进程 | | kill_by_pid | 操作 | 按 PID 关闭进程 | | kill_by_name | 操作 | 按进程名关闭进程（模糊匹配） | | kill_by_port_range | 操作 | 批量关闭端口范围内的所有进程 | | kill_process_tree | 操作 | 关闭进程及其所有子进程（进程树） |

安装

npm install
npm run build

MCP 客户端配置

Windsurf / Cursor（本地开发）

{
  "mcpServers": {
    "kill-port": {
      "command": "node",
      "args": ["D:/毕设/关闭项目运行mcp/dist/index.js"]
    }
  }
}

发布后使用 (npx)

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

Tool 详细说明

查询类工具

list_listening_ports — 列出所有监听端口

无参数。返回系统当前所有监听端口列表，包含端口号、PID、进程名、协议、状态、内存占用。

适用场景： AI 需要了解当前系统端口占用全貌。

输出示例：

当前共有 5 个端口正在监听:

端口 | PID   | 进程名       | 协议 | 状态      | 内存MB
-----+-------+--------------+------+-----------+-------
3000 | 12345 | node.exe     | TCP  | LISTENING | 85
5173 | 23456 | node.exe     | TCP  | LISTENING | 120
8080 | 34567 | java.exe     | TCP  | LISTENING | 512

find_by_port — 查找指定端口的进程

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | port | number | 是 | 要查找的端口号 (1-65535) |

适用场景： 启动项目前发现端口被占用，想知道是哪个进程占用了。

输出示例：

端口 3000 被以下 1 个进程占用:

- PID: 12345
  进程名: node.exe
  协议: TCP
  内存: 85 MB
  命令行: node D:\project\server.js

find_by_port_range — 查找端口范围内的进程

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | startPort | number | 是 | 起始端口号 | | endPort | number | 是 | 结束端口号 |

适用场景： 查看一段端口范围内的占用情况，如开发常用的 3000-3999。

check_port — 检查端口是否可用

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | port | number | 是 | 要检查的端口号 (1-65535) |

适用场景： 启动项目前确认端口空闲。通过 net.createServer 实际尝试监听来检测，比 netstat 更准确。含 5 秒超时保护。

输出示例：

✅ 端口 3000 可用

❌ 端口 3000 已被占用

占用进程:
  - PID: 12345, 进程名: node.exe, 协议: TCP

check_port_range — 批量检查端口可用性

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | startPort | number | 是 | 起始端口号 | | endPort | number | 是 | 结束端口号 |

适用场景： AI 需要找到可用端口来启动服务。范围限制最大 1000 个端口。

输出示例：

端口范围 3000-3010 检查结果:
  可用: 9 个
  占用: 2 个

可用端口: 3001, 3002, 3003, 3004, 3005, 3006, 3008, 3009, 3010

被占用端口:
  - 端口 3000: PID 12345 (node.exe)
  - 端口 3007: PID 23456 (node.exe)

get_system_info — 获取系统信息

无参数。返回操作系统、CPU、内存、Node.js 版本等信息。

适用场景： AI 需要了解运行环境来选择正确的命令或判断资源是否充足。

操作类工具

kill_by_port — 关闭指定端口的进程

| 参数 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | port | number | 是 | — | 要关闭的端口号 (1-65535) | | force | boolean | 否 | false | true=强制终止(SIGKILL), false=优雅关闭(SIGTERM) |

适用场景： 项目重启前释放端口。推荐流程：先 check_port → 再 kill_by_port → 最后启动项目。

安全保护： 如果端口被系统关键进程占用（如 svchost），会自动跳过并返回保护原因。

输出示例：

端口 3000 关闭操作成功:

✅ PID 12345 (node.exe): 成功优雅关闭进程 node.exe(PID: 12345)

受保护进程示例：

端口 135 关闭操作部分失败:

❌ PID 1088 (svchost.exe): "svchost.exe" 是受保护的关键系统进程: Windows 服务宿主（承载大量系统服务）| Service Host

kill_by_pid — 按 PID 关闭进程

| 参数 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | pid | number | 是 | — | 要关闭的进程 PID | | force | boolean | 否 | false | 是否强制关闭 |

适用场景： 已知进程 PID 时直接关闭。

安全保护： 自动进行 PID + 进程名 双重检查。即使 PID 不在保护列表中，如果该 PID 对应的进程名是系统关键进程（如 csrss、lsass、svchost 等），也会被拒绝。

输出示例：

✅ 成功优雅关闭进程 node.exe(PID: 12345)

受保护进程示例：

❌ "csrss.exe" 是受保护的系统核心进程: Windows 客户端/服务器运行子系统 | Client/Server Runtime Subsystem

kill_by_name — 按进程名关闭进程

| 参数 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | name | string | 是 | — | 进程名称（模糊匹配，如 "node"、"python"、"java"） | | force | boolean | 否 | false | 是否强制关闭 |

适用场景： 关闭所有同类进程，如 kill_by_name("node") 关闭所有 Node.js 进程。支持模糊匹配，"node" 会匹配 "node.exe"。

安全保护（三重）：

1. 前置检查 — 如果搜索的名称本身就是受保护进程名（如 "svchost"、"csrss"），直接拒绝，不会执行任何搜索
2. 逐个检查 — 匹配到的每个进程都会检查 PID + 进程名保护，受保护进程跳过并返回原因
3. MCP 自身保护 — MCP 服务进程不会被关闭

输出示例：

按名称 "node" 关闭进程: 2/3 成功

✅ PID 12345 (node.exe): 成功优雅关闭进程 node.exe(PID: 12345)
✅ PID 23456 (node.exe): 成功优雅关闭进程 node.exe(PID: 23456)
❌ PID 34567 (node.exe): PID 34567 是当前 MCP 服务进程，不允许关闭自身

尝试关闭受保护进程示例：

按名称 "svchost" 关闭进程: 0/1 成功

❌ PID 0: "svchost" 是受保护的关键系统进程: Windows 服务宿主（承载大量系统服务）| Service Host

kill_by_port_range — 批量关闭端口范围内的进程

| 参数 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | startPort | number | 是 | — | 起始端口号 | | endPort | number | 是 | — | 结束端口号 | | force | boolean | 否 | false | 是否强制关闭 |

适用场景： 一次性清理多个开发服务占用的端口，如 kill_by_port_range(3000, 3010)。范围限制最大 1000 个端口。同一 PID 只会关闭一次。

安全保护： 范围内的每个进程都会经过 PID + 进程名双重保护检查。系统关键进程会被跳过并在结果中显示保护原因。

kill_process_tree — 关闭进程树

| 参数 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | pid | number | 是 | — | 父进程的 PID | | force | boolean | 否 | false | 是否强制关闭 |

适用场景： 关闭主进程时子进程残留的情况，如 Node.js 的 child_process 产生的子进程。会递归查找所有后代进程，从最深层开始关闭。最大递归深度 10 层。

安全保护： 父进程和每个子进程都会经过 PID + 进程名双重保护检查。如果父进程是受保护的系统进程，整个操作直接拒绝。子进程中如有受保护进程会自动跳过。

AI 推荐调用流程

场景 1：启动项目前释放端口

1. check_port(3000)          → 检查端口是否可用
2. 如果被占用:
   kill_by_port(3000)        → 优雅关闭
3. 如果优雅关闭失败:
   kill_by_port(3000, true)  → 强制关闭
4. 启动项目

场景 2：批量清理开发环境

1. list_listening_ports()             → 查看全部占用
2. kill_by_port_range(3000, 9000)     → 批量清理

场景 3：查找可用端口

1. check_port_range(8000, 8020)       → 找到可用端口列表
2. 选择第一个可用端口启动服务

场景 4：关闭顽固进程

1. find_by_port(3000)                 → 查看进程详情
2. kill_process_tree(pid)             → 连同子进程一起关闭
3. 如果仍失败:
   kill_process_tree(pid, true)       → 强制关闭整个进程树

安全机制

多层进程保护体系

本服务内置完善的进程保护体系，防止 AI 或用户误关闭关键系统进程导致系统崩溃。

保护级别分为三层：

| 保护级别 | 说明 | 示例 | |---|---|---| | 🔴 system | 操作系统核心进程，关闭会导致蓝屏/内核崩溃 | csrss、smss、lsass、wininit、kernel_task、systemd | | 🟡 critical | 关键系统服务，关闭会导致系统不稳定或功能丧失 | svchost、dwm、explorer、WindowServer、Finder、gnome-shell | | 🔵 self | MCP 服务自身进程 | 当前 Node.js 进程 |

保护覆盖范围（80+ 个进程名）：

| 平台 | system 级别（核心） | critical 级别（关键服务） | |---|---|---| | Windows | csrss, smss, wininit, services, lsass, winlogon, ntoskrnl, registry 等 | svchost, dwm, explorer, conhost, ctfmon, msmpeng, audiodg, spoolsv 等 | | macOS | kernel_task, launchd | WindowServer, loginwindow, Finder, Dock, coreaudiod, mds, securityd 等 | | Linux | init, systemd | kthreadd, kworker, journald, sshd, dbus-daemon, gdm, gnome-shell, Xorg 等 |

保护检查流程：

kill 请求 → PID 保护检查 → 进程名保护检查 → 通过后才执行 kill
                 ↓                 ↓
          PID 0/1/4 拒绝    匹配 80+ 系统进程名则拒绝
          SELF_PID 拒绝     返回保护级别和中英文原因

其他安全策略

| 安全策略 | 说明 | |---|---| | 优雅关闭优先 | 默认 SIGTERM/WM_CLOSE，超时 3 秒后提示使用 force | | Windows 自动降级 | 优雅关闭失败时自动降级为强制关闭 | | 端口范围限制 | 批量操作最大 1000 个端口 | | 检测超时保护 | check_port 含 5 秒超时，防止 hang | | 递归深度限制 | kill_process_tree 最大递归 10 层 | | 权限提示 | EACCES/管理员权限不足时明确提示 |

跨平台实现

| 功能 | Windows | macOS | Linux | |---|---|---|---| | 端口查询 | netstat -ano | lsof -iTCP | lsof / ss -tlnp | | 进程信息 | tasklist /FO CSV | ps | ps | | 命令行获取 | PowerShell Get-CimInstance（批量缓存） | ps -o args | ps -o args | | 杀进程 | taskkill / taskkill /F | process.kill() | process.kill() | | 进程存活检测 | tasklist /FI "PID eq ..." | process.kill(pid, 0) | process.kill(pid, 0) | | 子进程查询 | PowerShell Get-CimInstance | pgrep -P | pgrep -P |

发布到 npm

npm login
npm publish

English Documentation

A cross-platform MCP (Model Context Protocol) server for process & port management. Supports Windows / macOS / Linux.

Helps AI close processes occupying specified ports before re-running projects, avoiding port conflicts.

Features (11 Tools)

| Tool | Type | Description | |---|---|---| | list_listening_ports | Query | List all listening ports with process info (PID, name, memory) | | find_by_port | Query | Find processes occupying a specific port (with memory, cmdline) | | find_by_port_range | Query | Find all occupied ports in a range | | check_port | Query | Check if a single port is available (with timeout protection) | | check_port_range | Query | Batch-check port range availability (returns available/occupied lists) | | get_system_info | Query | Get OS, CPU, memory, Node.js version info | | kill_by_port | Action | Kill all processes on a specific port | | kill_by_pid | Action | Kill a process by PID | | kill_by_name | Action | Kill processes by name (fuzzy match) | | kill_by_port_range | Action | Batch-kill all processes in a port range | | kill_process_tree | Action | Kill a process and all its child processes (process tree) |

Installation

npm install
npm run build

MCP Client Configuration

Windsurf / Cursor (Local Dev)

{
  "mcpServers": {
    "kill-port": {
      "command": "node",
      "args": ["D:/毕设/关闭项目运行mcp/dist/index.js"]
    }
  }
}

After Publishing (npx)

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

Tool Reference

Query Tools

list_listening_ports — List all listening ports

No parameters. Returns all currently listening ports with port number, PID, process name, protocol, state, and memory usage.

When to use: AI needs an overview of current port usage on the system.

Example output:

5 ports currently listening:

Port | PID   | Name         | Proto | State     | MemMB
-----+-------+--------------+-------+-----------+------
3000 | 12345 | node.exe     | TCP   | LISTENING | 85
5173 | 23456 | node.exe     | TCP   | LISTENING | 120
8080 | 34567 | java.exe     | TCP   | LISTENING | 512

find_by_port — Find processes on a specific port

| Parameter | Type | Required | Description | |---|---|---|---| | port | number | Yes | Port number to look up (1-65535) |

When to use: A port is occupied and you need to identify which process is using it before deciding to kill it.

Example output:

Port 3000 is occupied by 1 process:

- PID: 12345
  Name: node.exe
  Protocol: TCP
  Memory: 85 MB
  Command: node D:\project\server.js

find_by_port_range — Find processes in a port range

| Parameter | Type | Required | Description | |---|---|---|---| | startPort | number | Yes | Start port | | endPort | number | Yes | End port |

When to use: Survey port occupation across a range, e.g. common dev ports 3000-3999.

Example output:

2 ports occupied in range 3000-3010:

- Port 3000 (TCP)
  PID: 12345
  Name: node.exe
  Memory: 85 MB
  Command: node server.js

- Port 3007 (TCP)
  PID: 23456
  Name: node.exe
  Memory: 60 MB
  Command: node dev.js

check_port — Check if a port is available

| Parameter | Type | Required | Description | |---|---|---|---| | port | number | Yes | Port number to check (1-65535) |

When to use: Verify a port is free before starting a service. Uses actual net.createServer listen attempt — more accurate than netstat. Includes 5s timeout protection.

Example output:

✅ Port 3000 is available

❌ Port 3000 is occupied

Occupying processes:
  - PID: 12345, Name: node.exe, Protocol: TCP

check_port_range — Batch-check port availability

| Parameter | Type | Required | Description | |---|---|---|---| | startPort | number | Yes | Start port | | endPort | number | Yes | End port |

When to use: AI needs to find available ports to start services. Max range: 1000 ports.

Example output:

Port range 3000-3010 check results:
  Available: 9
  Occupied: 2

Available ports: 3001, 3002, 3003, 3004, 3005, 3006, 3008, 3009, 3010

Occupied ports:
  - Port 3000: PID 12345 (node.exe)
  - Port 3007: PID 23456 (node.exe)

get_system_info — Get system information

No parameters. Returns OS type, architecture, hostname, CPU model/cores, memory usage, uptime, Node.js version, home and temp directories.

When to use: AI needs to understand the runtime environment for choosing correct commands or checking resource availability.

Example output:

OS: Windows_NT 10.0.22631 (win32)
Architecture: x64
Hostname: MY-PC
CPU: 13th Gen Intel(R) Core(TM) i7-13700H (20 cores)
Memory: 12.5GB used / 16.0GB total (3.5GB free)
Uptime: 48.3 hours
Node.js: v20.11.0
Home: C:\Users\user
Temp: C:\Users\user\AppData\Local\Temp

Action Tools

kill_by_port — Kill processes on a specific port

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | port | number | Yes | — | Port number (1-65535) | | force | boolean | No | false | true=SIGKILL/force, false=SIGTERM/graceful |

When to use: Release a port before restarting a project. Recommended flow: check_port → kill_by_port → start project.

Safety: If a port is occupied by a critical system process (e.g. svchost), it is automatically skipped and the protection reason is returned.

Example output:

Port 3000 kill operation succeeded:

✅ PID 12345 (node.exe): Successfully closed process node.exe(PID: 12345) gracefully

Protected process example:

Port 135 kill operation partially failed:

❌ PID 1088 (svchost.exe): "svchost.exe" is a protected critical system process: Windows Service Host | Service Host

kill_by_pid — Kill a process by PID

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | pid | number | Yes | — | Process ID to kill | | force | boolean | No | false | Force kill |

When to use: You already know the exact PID to kill.

Safety: Automatically performs PID + process name dual protection check. Even if a PID is not in the protected PID list, if the process name is a critical system process (e.g. csrss, lsass, svchost), it will be refused.

Example output:

✅ Successfully closed process node.exe(PID: 12345) gracefully

Protected process example:

❌ "csrss.exe" is a protected system core process: Windows Client/Server Runtime Subsystem | Client/Server Runtime Subsystem

kill_by_name — Kill processes by name

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | name | string | Yes | — | Process name (fuzzy match, e.g. "node", "python", "java") | | force | boolean | No | false | Force kill |

When to use: Kill all processes of a type, e.g. kill_by_name("node") kills all Node.js processes. Supports fuzzy match — "node" matches "node.exe".

Safety (triple protection):

1. Pre-check — If the search name itself is a protected process name (e.g. "svchost", "csrss"), the request is refused immediately without any search
2. Per-process check — Each matched process is checked for PID + name protection; protected processes are skipped with reason
3. MCP self-protection — The MCP server process will not be killed

Example output:

Kill by name "node": 2/3 succeeded

✅ PID 12345 (node.exe): Successfully closed process node.exe(PID: 12345) gracefully
✅ PID 23456 (node.exe): Successfully closed process node.exe(PID: 23456) gracefully
❌ PID 34567 (node.exe): PID 34567 is the current MCP server process, cannot kill self

Attempting to kill a protected process:

Kill by name "svchost": 0/1 succeeded

❌ PID 0: "svchost" is a protected critical system process: Windows Service Host | Service Host

kill_by_port_range — Batch-kill processes in a port range

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | startPort | number | Yes | — | Start port | | endPort | number | Yes | — | End port | | force | boolean | No | false | Force kill |

When to use: Clean up multiple dev services at once, e.g. kill_by_port_range(3000, 3010). Max range: 1000 ports. Same PID is only killed once.

Safety: Each process in the range is checked with PID + process name dual protection. Critical system processes are skipped and the reason is shown in results.

Example output:

Port range 3000-3010 kill operation: 2/2 succeeded

✅ PID 12345 (node.exe): Successfully closed process node.exe(PID: 12345) gracefully
✅ PID 23456 (node.exe): Successfully closed process node.exe(PID: 23456) gracefully

kill_process_tree — Kill a process tree

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | pid | number | Yes | — | Parent process PID | | force | boolean | No | false | Force kill |

When to use: A main process has orphaned child processes (e.g. Node.js child_process spawns). Recursively finds all descendants and kills from deepest level up. Max recursion depth: 10 levels.

Safety: Both parent and each child process are checked with PID + process name dual protection. If the parent is a protected system process, the entire operation is refused. Protected child processes are automatically skipped.

Example output:

Process tree kill result (3/3 succeeded):

✅ PID 34567 (node.exe): Successfully closed child process (PID: 34567) gracefully
✅ PID 23456 (node.exe): Successfully closed child process (PID: 23456) gracefully
✅ PID 12345 (node.exe): Successfully closed parent process (PID: 12345) gracefully

Recommended AI Workflows

Workflow 1: Release port before starting project

1. check_port(3000)          → Check if port is free
2. If occupied:
   kill_by_port(3000)        → Graceful shutdown
3. If graceful fails:
   kill_by_port(3000, true)  → Force kill
4. Start project

Workflow 2: Batch clean dev environment

1. list_listening_ports()             → View all occupied ports
2. kill_by_port_range(3000, 9000)     → Batch clean

Workflow 3: Find available port

1. check_port_range(8000, 8020)       → Get list of free ports
2. Pick the first available port

Workflow 4: Kill stubborn process

1. find_by_port(3000)                 → View process details
2. kill_process_tree(pid)             → Kill with children
3. If still alive:
   kill_process_tree(pid, true)       → Force kill entire tree

Safety Mechanisms

Multi-Layer Process Protection

Built-in comprehensive process protection to prevent AI or users from accidentally killing critical system processes.

Three protection levels:

| Level | Description | Examples | |---|---|---| | 🔴 system | OS core processes — killing causes BSOD/kernel panic | csrss, smss, lsass, wininit, kernel_task, systemd | | 🟡 critical | Critical system services — killing causes instability | svchost, dwm, explorer, WindowServer, Finder, gnome-shell | | 🔵 self | MCP server's own process | Current Node.js process |

Protection coverage (80+ process names):

| Platform | system level (core) | critical level (services) | |---|---|---| | Windows | csrss, smss, wininit, services, lsass, winlogon, ntoskrnl, registry, etc. | svchost, dwm, explorer, conhost, ctfmon, msmpeng, audiodg, spoolsv, etc. | | macOS | kernel_task, launchd | WindowServer, loginwindow, Finder, Dock, coreaudiod, mds, securityd, etc. | | Linux | init, systemd | kthreadd, kworker, journald, sshd, dbus-daemon, gdm, gnome-shell, Xorg, etc. |

Protection check flow:

kill request → PID check → Process name check → Execute kill only if passed
                  ↓                ↓
          PID 0/1/4 refused   Matches 80+ system process names → refused
          SELF_PID refused    Returns protection level and bilingual reason

Other Safety Policies

| Policy | Description | |---|---| | Graceful first | Default SIGTERM/WM_CLOSE, 3s timeout before suggesting force mode | | Windows auto-fallback | Graceful kill failure auto-downgrades to forced kill | | Port range limit | Max 1000 ports per batch operation | | Check timeout | check_port has 5s timeout to prevent hanging | | Recursion depth limit | kill_process_tree max 10 levels deep | | Permission hints | Clear messages when EACCES / admin rights are needed |

Cross-Platform Implementation

| Feature | Windows | macOS | Linux | |---|---|---|---| | Port query | netstat -ano | lsof -iTCP | lsof / ss -tlnp | | Process info | tasklist /FO CSV | ps | ps | | Command line | PowerShell Get-CimInstance (batched+cached) | ps -o args | ps -o args | | Kill process | taskkill / taskkill /F | process.kill() | process.kill() | | Alive check | tasklist /FI "PID eq ..." | process.kill(pid, 0) | process.kill(pid, 0) | | Child process | PowerShell Get-CimInstance | pgrep -P | pgrep -P |

Publish to npm

npm login
npm publish

License

MIT