NmapMCP

NmapMCP

本番品質の Nmap MCP（Model Context Protocol）サーバーです。単なる薄いラッパーではありません。

多くの Nmap MCP サーバーは、nmap の出力をそのまま生テキストで AI に渡して終わりです。NmapMCP は nmap の XML 出力を構造化 JSON に解析し、汎用的な nmap_scan ひとつではなく、用途に特化した 35 個のツールを提供します。さらに、任意のネットワークスキャンを実行するツールに実際に必要な安全対策を追加しています。

⚠️ 教育目的でのみ使用してください。 自分が所有するホストやネットワーク、またはテストを明示的に許可されているホストやネットワークのみをスキャンしてください。詳しくは、以下の責任ある使用をご覧ください。

---

他とは異なる点

生テキストではなく、構造化された出力。 nmap の XML 出力を完全に解析し、整った JSON に変換します。OS フィンガープリント、MAC ベンダー検索、CPE 文字列、ポートごとの NSE スクリプト結果、traceroute のホップ数、稼働時間などが含まれるため、AI アシスタントは stdout の長い出力に正規表現を適用せず、フィールドを使って推論できます。

汎用スキャンひとつではなく、用途に特化した 35 個のツール。 AI に正しい NSE スクリプト名やフラグの組み合わせを覚えさせるのではなく、ユースケースごとに専用ツールを用意しています。ssl_scan、smb_vuln_scan、database_scan、dns_enum、rdp_scan、ftp_scan、ssh_audit など、適切なスクリプトとフラグがあらかじめ設定されています。

スキャン履歴と差分比較。 list_scan_history、get_scan_result、diff_scans を使えば、スキャンを実行し、後で再度実行して、「何が変わったか」を確認できます。ポートの開閉やバージョンの変更を構造化された差分として出力します。ほとんどの Nmap MCP サーバーには、そもそも履歴を追跡する機能がありません。

セキュリティガードレールを標準装備。

• フラグの許可リスト — すべての nmap フラグは、シェルに渡される前に明示的な許可リストと照合されます。任意の値は通過できません
• ターゲットの検証 — 入力を正規表現でチェックし、長さを制限します
• プライベート範囲ガード — デフォルトではパブリック IP をブロックします。スキャンするには、NMAP_ALLOW_PUBLIC=1 を明示的に設定する必要があります
• 同時実行数の制限 — セマフォで並列スキャンを 3 件に制限するため、AI が同時に全ポートスキャンを実行してネットワークを誤って飽和させることはありません
• 厳格なタイムアウト — スキャンがハングした場合、1800s 後に必ず終了します

2 段階のネットワークインベントリ。 network_inventory はまず ping スイープを実行し、応答したホストに対してのみサービス検出を実行します。/24 全体にサービススキャンをやみくもに実行するより、はるかに効率的です。

人が読みやすい要約。 get_host_summary は、ホスト名、OS の推定、オープンポート、スクリプトの注目点、traceroute を含む書式付きテキストレポートを返します。モデルが解析するためだけでなく、人が直接読むことを想定しています。

---

ツールリファレンス

カテゴリ	ツール
一般的なスキャン	nmap_scan、structured_scan、quick_scan、top_ports_scan、full_port_scan、check_single_port
ホスト検出	ping_sweep、arp_scan、network_inventory
スキャン手法	syn_stealth_scan、udp_scan、ipv6_scan
サービス／OS	service_scan、os_detection、aggressive_scan、banner_grab
脆弱性	vuln_scan、safe_vuln_scan、smb_vuln_scan
プロトコル監査	ssl_scan、http_enum、dns_enum、smb_enum、ftp_scan、ssh_audit、rdp_scan、database_scan
ネットワーク分析	firewall_detection、traceroute_scan
スクリプト	script_scan（名前を指定して任意の NSE スクリプト／カテゴリを実行）
履歴とレポート	list_scan、list_scan_history、get_scan_result、diff_scans、get_host_summary

Claude に接続した後のプロンプト例：

run a quick_scan on 192.168.1.100
get_host_summary on 192.168.1.1
run a vuln_scan on 192.168.1.50
network_inventory of 192.168.1.0/24
diff_scans between scan_id_a and scan_id_b

---

セットアップ

必要条件

必要条件	バージョン	備考
Python	3.13+
Nmap	7.9+	実際にスキャンを実行するバイナリ
uv	最新	Python パッケージマネージャー
Claude Desktop	最新	または MCP 対応クライアント

1. Python 3.13+ をインストールする

python.org からダウンロードしてください。Windows では、インストール中に 「Add Python to PATH」 にチェックを入れてください。次のコマンドで確認します。

python --version

2. Nmap をインストールする

nmap.org からダウンロードしてください。Windows ではインストール中に Npcap のチェックを外さないでください。次のコマンドで確認します。

nmap --version

3. uv をインストールする

pip install uv

4. プロジェクトを取得する

git clone https://github.com/<your-username>/NmapMCP.git
cd NmapMCP

5. サーバーが使用する Nmap バイナリを指定する

デフォルトでは、サーバーは NMAP_PATH 環境変数を使って Nmap を検索します（見つからない場合は Windows のデフォルトパスを使用します）。実際の nmap のパスを設定してください。macOS/Linux では通常 nmap または /usr/bin/nmap です。Windows では、スラッシュを使った 8.3 形式の短いパスが必要です。例：C:/PROGRA~1/Nmap/nmap.exe（where nmap でパスを確認し、空白が含まれている場合は短いパスに変換してください）。

ソースを編集するのではなく、環境変数として設定してください。

export NMAP_PATH=/usr/bin/nmap   # macOS/Linux
set NMAP_PATH=C:/PROGRA~1/Nmap/nmap.exe   # Windows

6. 依存関係をインストールする

uv venv
uv pip install -e .

7. MCP クライアントを設定する

Claude Desktop の設定ファイル（Windows では %APPDATA%\Claude\claude_desktop_config.json、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "NmapMCP": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/NmapMCP", "run", "main.py"]
    }
  }
}

Claude Desktop を再起動し、ツールアイコンが表示されることを確認してください。

Docker

コンテナ環境でのデプロイ用に Dockerfile が含まれています。詳細はそちらを参照してください。

---

責任ある使用

このプロジェクトは、教育および許可を得たテストのみを目的として公開されています。Nmap のようなネットワークスキャンツールは、許可なくシステムを調査するために悪用される可能性があり、多くの法域で違法です。

• 自分が所有する、またはテストの明示的な書面による許可を得ているホスト、ネットワーク、サービスのみをスキャンしてください
• パブリック IP のスキャンはデフォルトで無効です（上書きするには NMAP_ALLOW_PUBLIC=1 が必要です）。特に必要で、かつ許可を得ている場合を除き、無効のままにしてください
• このリポジトリのメンテナーは、悪用について責任を負いません

---

トラブルシューティング

「nmap が見つからない」 — ターミナルで nmap --version が動作すること、および NMAP_PATH が正しいバイナリを指していることを確認してください。

すべてのスキャンで「稼働中のホストが 0 件」と表示される（Windows） — 多くの場合、Npcap の権限に関する問題です。ping_sweep／arp_scan の代わりに quick_scan または get_host_summary（TCP 接続ベースで、管理者権限は不要）を使用するか、ターミナル／Claude Desktop を管理者として実行してください。

Claude Desktop にツールアイコンが表示されない — 設定 JSON を検証し、パスが正しく、絶対パスであることを確認してから、Claude Desktop を完全に終了して再度開いてください。

一部のスキャンには昇格した権限が必要です — 通常、syn_stealth_scan、udp_scan、arp_scan、os_detection には管理者／root 権限が必要です。

---

ロードマップ／既知の制限事項

現状を率直に示します。

• 自動テストスイートはまだありません
• 単一ファイル構成（main.py）です。現在の用途では問題ありませんが、将来的に runner/parser/validator/tools の各モジュールに分割すると、保守性が向上します
• スキャン履歴はメモリ内にのみ保存され、再起動後には保持されません。永続的な監査ログもまだありません
• ターゲットごとのレート制限はありません（全体の並列数のみ上限があります）

---

ライセンス

MIT — LICENSE を参照してください。