port-doctor-mcp

A local stdio MCP server based on FastMCP that checks development port usage and terminates the corresponding process by port.

Features

• check_port_status(port: int): checks whether a port is occupied, and returns the PID, name, RSS memory usage, protocol, and connection state of the occupying process.

• kill_process_by_port(port: int, force: bool = True): terminates the process occupying the port. Uses forceful termination by default; pass force=false to use the gentler terminate. The server will not terminate itself.

• scan_common_dev_ports(): scans common development ports: 3000, 3001, 4173, 5000, 5173, 8000, 8001, 8080, 8081, 8888, 9000.

Related MCP server: localhost-mcp

Installation

Requires Python 3.10 or higher.

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

Verify that the current interpreter actually has the dependencies installed:

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

If ModuleNotFoundError still appears here, it means the Python used to install dependencies and the one used to run the server are not the same. Do not just run Invalidate Caches; instead, in PyCharm select this project's .venv/bin/python under Settings -> Project -> Python Interpreter, and use the same interpreter in the Run Configuration.

For example, the project interpreter path should be similar to:

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

Windows example:

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

Running

This is a stdio server. Once started, it waits for MCP clients to communicate via stdin/stdout and does not provide an HTTP port.

python server.py

You can also use the FastMCP CLI:

fastmcp run server.py

For development and debugging, you can use MCP Inspector (subject to the support of your installed FastMCP CLI):

fastmcp dev inspector server.py

After running python server.py directly, it is normal for the terminal to have no ordinary output and to keep waiting for input: the stdio MCP server waits for the client to send JSON-RPC messages via stdin/stdout. Do not treat "the process has not exited" as a startup failure.

Manual Testing Checklist

Run in the project root directory:

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 should show the following three tools:

• check_port_status: required port, an integer.

• kill_process_by_port: required port, optional force, default true.

• scan_common_dev_ports: no parameters.

Testing with Inspector

Run:

fastmcp dev inspector server.py

In the opened Inspector, test in order:

1. Call check_port_status, passing 5000 or 8000.

2. Call scan_common_dev_ports and confirm it returns scanned_ports and occupied_ports.

3. Start a dedicated test service:

   python -m http.server 8765 --bind 127.0.0.1

4. Call check_port_status(8765) and confirm you can see the Python process's PID, name, and memory.

5. Call kill_process_by_port(8765, force=false), confirm it returns success: true, then close the test terminal.

Do not test kill_process_by_port directly against important processes such as databases, IDEs, or system services. This tool defaults to force=true and sends a forced termination signal.

Checking the schema with the FastMCP CLI

fastmcp inspect server.py --format mcp

Check whether the tool names, descriptions, parameter types, and default values in the output are correct.

MCP Client Configuration

Replace the path below with the absolute path of this project, then place it in the configuration of an MCP-capable client:

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

Windows example:

{
  "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 only handles GitHub repository directory information; it will not fix your local Python interpreter. After installation, other users still need to create a virtual environment and run pip install -r requirements.txt.

Publishing to MCP.so

MCP.so is an MCP server directory; it will not turn a local stdio process into a public HTTP service. Before publishing, commit this project to a public GitHub repository, then open:

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

Fill in:

• Repository URL: your GitHub repository URL.

• Name: port-doctor-mcp.

The submission page may offer a paid expedited publishing option; whether you purchase it does not affect whether this project's code runs. After discovering the project in the directory, users still need to configure the local Python environment following the installation steps above.

Return Value Example

check_port_status(8000) returns a structure similar to:

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

Safety Notes

kill_process_by_port is a tool with side effects. The default force=true sends a forced termination signal and may cause loss of unsaved data; it is recommended to call check_port_status first to confirm the PID, then decide whether to terminate. When reading other users' process information or terminating protected processes, the operating system may return permission errors.

License

See LICENSE.