port-doctor-mcp

一个基于 FastMCP 的本地 stdio MCP 服务器，用于检查开发端口占用情况，并按端口终止对应进程。

功能

• check_port_status(port: int)：检查端口是否被占用，返回占用进程的 PID、名称、RSS 内存占用、协议和连接状态。

• kill_process_by_port(port: int, force: bool = True)：终止占用端口的进程。默认使用强制终止；传入 force=false 使用较温和的 terminate。服务器不会终止自身。

• scan_common_dev_ports()：扫描常见开发端口：3000、3001、4173、5000、5173、8000、8001、8080、8081、8888、9000。

Related MCP server: localhost-mcp

安装

需要 Python 3.10 或更高版本。

python -m venv .venv
source .venv/bin/activate       # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

验证当前解释器确实安装了依赖：

python -c "import sys, psutil, fastmcp; print(sys.executable); print('psutil', psutil.__version__); print('fastmcp', fastmcp.__version__)"

如果这里仍然提示 ModuleNotFoundError，说明安装依赖和运行服务器使用的不是同一个 Python。不要只执行 Invalidate Caches；请在 PyCharm 的 Settings -> Project -> Python Interpreter 中选择本项目的 .venv/bin/python，并在 Run Configuration 中使用相同解释器。

例如项目的解释器路径应类似：

/path/to/port-doctor-mcp/.venv/bin/python

Windows 示例：

C:\path\to\port-doctor-mcp\.venv\Scripts\python.exe

运行

这是 stdio 服务器，启动后会等待 MCP 客户端通过 stdin/stdout 通信，不会提供 HTTP 端口。

python server.py

也可以使用 FastMCP CLI：

fastmcp run server.py

开发调试可使用 MCP Inspector（以当前安装的 FastMCP CLI 支持为准）：

fastmcp dev inspector server.py

直接运行 python server.py 后终端没有普通输出、一直等待输入是正常现象：stdio MCP 服务器会等待客户端通过 stdin/stdout 发送 JSON-RPC 消息。不要把“进程没有退出”当成启动失败。

手动测试清单

在项目根目录执行：

source .venv/bin/activate
python -m pip check
python -m py_compile server.py
git diff --check
fastmcp list server.py --input-schema --output-schema --json

fastmcp list 应显示以下三个工具：

• check_port_status：必填 port，整数。

• kill_process_by_port：必填 port，可选 force，默认 true。

• scan_common_dev_ports：无参数。

使用 Inspector 测试

执行：

fastmcp dev inspector server.py

在打开的 Inspector 中依次测试：

1. 调用 check_port_status，传入 5000 或 8000。

2. 调用 scan_common_dev_ports，确认返回 scanned_ports 和 occupied_ports。

3. 启动一个专用测试服务：

   python -m http.server 8765 --bind 127.0.0.1

4. 调用 check_port_status(8765)，确认能看到 Python 进程的 PID、名称和内存。

5. 调用 kill_process_by_port(8765, force=false)，确认返回 success: true，然后关闭测试终端。

不要直接对数据库、IDE、系统服务等重要进程测试 kill_process_by_port。该工具默认 force=true，会发送强制终止信号。

用 FastMCP CLI 检查 schema

fastmcp inspect server.py --format mcp

检查输出中的工具名称、描述、参数类型和默认值是否正确。

MCP 客户端配置

将下面的路径替换为本项目的绝对路径，然后放入支持 MCP 的客户端配置中：

{
  "mcpServers": {
    "port-doctor-mcp": {
      "command": "/absolute/path/to/port-doctor-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/port-doctor-mcp/server.py"]
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "port-doctor-mcp": {
      "command": "C:\\path\\to\\port-doctor-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\port-doctor-mcp\\server.py"]
    }
  }
}

MCP.so 提交的是 GitHub 仓库目录信息，不会替你修复本地 Python 解释器。其他用户安装后仍需先创建虚拟环境并执行 pip install -r requirements.txt。

发布到 MCP.so

MCP.so 是 MCP 服务器目录，不会把本地 stdio 进程变成公网 HTTP 服务。发布前先把本项目提交到公开 GitHub 仓库，然后打开：

https://mcp.so/submit?type=server

填写：

• Repository URL：你的 GitHub 仓库地址。

• Name：port-doctor-mcp。

提交页面可能提供付费加急发布选项；是否购买不影响本项目代码运行。用户从目录发现项目后，仍需按上面的安装步骤配置本地 Python 环境。

返回值示例

check_port_status(8000) 返回结构类似：

{
  "port": 8000,
  "in_use": true,
  "process_count": 1,
  "processes": [
    {
      "pid": 12345,
      "name": "python",
      "memory_rss_bytes": 52428800,
      "memory_rss_mb": 50.0,
      "connections": [
        {
          "protocol": "tcp",
          "local_address": "127.0.0.1:8000",
          "status": "LISTEN"
        }
      ]
    }
  ]
}

安全提示

kill_process_by_port 是有副作用的工具。默认 force=true 会发送强制终止信号，可能丢失未保存的数据；建议先调用 check_port_status 确认 PID，再决定是否终止。读取其他用户进程信息或终止受保护进程时，操作系统可能返回权限错误。

许可证

见 LICENSE。