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 は次の 3 つのツールを表示するはずです：

• 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 でスキーマを確認する

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 リポジトリの URL。

• 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 を参照してください。