port-doctor-mcp

Un servidor MCP stdio local basado en FastMCP para comprobar la ocupación de puertos de desarrollo y terminar los procesos correspondientes según el puerto.

Funciones

• check_port_status(port: int): comprueba si el puerto está ocupado y devuelve el PID, el nombre, el uso de memoria RSS, el protocolo y el estado de conexión del proceso que lo ocupa.

• kill_process_by_port(port: int, force: bool = True): termina el proceso que ocupa el puerto. Por defecto usa terminación forzada; si se pasa force=false, usa un terminate más suave. El servidor no se termina a sí mismo.

• scan_common_dev_ports(): escanea puertos de desarrollo comunes: 3000, 3001, 4173, 5000, 5173, 8000, 8001, 8080, 8081, 8888, 9000.

Related MCP server: localhost-mcp

Instalación

Requiere Python 3.10 o superior.

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

Comprueba que el intérprete actual tiene realmente instaladas las dependencias:

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

Si aquí sigue apareciendo ModuleNotFoundError, significa que la instalación de dependencias y la ejecución del servidor no están usando el mismo Python. No te limites a ejecutar Invalidate Caches; en PyCharm, selecciona .venv/bin/python de este proyecto en Settings -> Project -> Python Interpreter y usa el mismo intérprete en la Run Configuration.

Por ejemplo, la ruta del intérprete del proyecto debería ser similar a:

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

Ejemplo en Windows:

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

Ejecución

Este es un servidor stdio. Al iniciarse, espera que el cliente MCP se comunique a través de stdin/stdout; no proporciona un puerto HTTP.

python server.py

También puedes usar la CLI de FastMCP:

fastmcp run server.py

Para depurar durante el desarrollo, puedes usar MCP Inspector (según el soporte de la versión de FastMCP CLI actualmente instalada):

fastmcp dev inspector server.py

Al ejecutar directamente python server.py, es normal que la terminal no muestre salida normal y se quede esperando entrada: un servidor MCP stdio espera que el cliente envíe mensajes JSON-RPC por stdin/stdout. No interpretes «el proceso no sale» como un fallo de arranque.

Lista de comprobación de pruebas manuales

En la raíz del proyecto, ejecuta:

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 debería mostrar las siguientes tres herramientas:

• check_port_status: obligatorio port, entero.

• kill_process_by_port: obligatorio port, opcional force, por defecto true.

• scan_common_dev_ports: sin parámetros.

Probar con Inspector

Ejecuta:

fastmcp dev inspector server.py

En el Inspector abierto, prueba en orden:

1. Invoca check_port_status con 5000 o 8000.

2. Invoca scan_common_dev_ports y confirma que devuelve scanned_ports y occupied_ports.

3. Inicia un servicio de prueba dedicado:

   python -m http.server 8765 --bind 127.0.0.1

4. Invoca check_port_status(8765) y confirma que puedes ver el PID, el nombre y la memoria del proceso de Python.

5. Invoca kill_process_by_port(8765, force=false) y confirma que devuelve success: true; luego cierra la terminal de prueba.

No pruebes kill_process_by_port directamente contra procesos importantes como bases de datos, IDE o servicios del sistema. Esta herramienta usa force=true por defecto y enviará una señal de terminación forzada.

Comprobar el esquema con FastMCP CLI

fastmcp inspect server.py --format mcp

Comprueba que en la salida los nombres de las herramientas, las descripciones, los tipos de parámetros y los valores predeterminados sean correctos.

Configuración del cliente MCP

Reemplaza la siguiente ruta por la ruta absoluta de este proyecto e introdúcela en la configuración de un cliente compatible con MCP:

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

Ejemplo en 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"]
    }
  }
}

A MCP.so se envía la información del directorio del repositorio de GitHub; no arreglará tu intérprete de Python local. Después de la instalación, otros usuarios aún deben crear un entorno virtual y ejecutar pip install -r requirements.txt.

Publicar en MCP.so

MCP.so es un directorio de servidores MCP; no convierte un proceso stdio local en un servicio HTTP público. Antes de publicar, sube primero este proyecto a un repositorio público de GitHub y luego abre:

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

Completa:

• Repository URL: la dirección de tu repositorio de GitHub.

• Name: port-doctor-mcp.

La página de envío puede ofrecer una opción de publicación acelerada de pago; comprarla o no no afecta la ejecución del código de este proyecto. Cuando los usuarios encuentren el proyecto en el directorio, aún deberán configurar el entorno Python local siguiendo los pasos de instalación anteriores.

Ejemplo de valor de retorno

check_port_status(8000) devuelve una estructura similar a:

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

Aviso de seguridad

kill_process_by_port es una herramienta con efectos secundarios. Por defecto force=true envía una señal de terminación forzada, lo que puede provocar la pérdida de datos no guardados. Se recomienda llamar primero a check_port_status para confirmar el PID y luego decidir si terminar el proceso. Al leer información de procesos de otros usuarios o intentar terminar procesos protegidos, el sistema operativo puede devolver errores de permisos.

Licencia

Ver LICENSE.