MCP Port Scanner

🚀 MCP智能端口掃描器

基於MCP協議的智能分層端口掃描服務，專為AI助手和開發工具設計，可快速發現網絡資產和潛在風險，保障服務正常運行。

🚀 快速開始

環境準備

# 克隆項目
git clone https://github.com/relaxcloud-cn/port-scanner.git
cd mcp-port-scanner

# 安裝Python依賴
pip install -r requirements.txt
pip install mcp

# 安裝RustScan（必需）
# macOS
brew install rustscan

# Linux
wget https://github.com/RustScan/RustScan/releases/download/2.0.1/rustscan_2.0.1_amd64.deb
sudo dpkg -i rustscan_2.0.1_amd64.deb

Docker快速啟動

# 啟動stdio模式服務（本地Cursor集成）
docker-compose up -d mcp-port-scanner

# 啟動SSE模式服務（支持遠程訪問）
docker-compose up -d mcp-port-scanner-sse

# 查看服務狀態
docker-compose ps

✨ 主要特性

智能分層掃描

• 🧠 動態決策：根據端口數量自動調整掃描深度，平衡效率與覆蓋率。
• 🎯 三層架構：端口掃描 → HTTP檢測 → Web深度探測，逐層深入。
• ⚡ 極速性能：基於RustScan，比傳統掃描器快10倍。

多種接口支持

• 🔌 MCP協議：原生支持stdio和HTTP/SSE兩種傳輸模式。
• 📊 實時反饋：SSE推送進度，讓掃描過程可視化。
• 🤖 AI集成：與Cursor等AI工具無縫集成。

適用場景

• 安全審計：快速發現網絡資產和潛在風險。
• 運維監控：定期掃描基礎設施，確保服務正常。
• 開發測試：驗證端口配置和服務部署。
• AI輔助分析：通過MCP協議實現智能化安全分析。

🔧 技術細節

系統架構

graph TB
    subgraph "接口層 (Interfaces)"
        CLI["🖥️ CLI<br/>命令行接口"]
        MCP["🔌 MCP<br/>協議接口"]
        HTTP["🌐 HTTP<br/>Web接口"]
        SSE["📡 Cursor SSE<br/>實時推送"]
    end
    
    subgraph "適配器層 (Adapters)"
        CLI_ADAPTER["CLI適配器"]
        MCP_LOCAL["MCP本地適配器"]
        MCP_REMOTE["MCP遠程適配器"]
        SSE_ADAPTER["SSE適配器"]
    end
    
    subgraph "服務層 (Service Layer)"
        SCANNER["🔍 Scanner<br/>端口掃描器"]
        DETECTOR["🔎 Detector<br/>HTTP檢測器"]
        PROBER["🕵️ Prober<br/>Web探測器"]
        MODELS["📊 Models<br/>數據模型"]
    end
    
    CLI --> CLI_ADAPTER
    MCP --> MCP_LOCAL
    MCP --> MCP_REMOTE
    HTTP --> MCP_REMOTE
    SSE --> SSE_ADAPTER
    
    CLI_ADAPTER --> SCANNER
    MCP_LOCAL --> SCANNER
    MCP_REMOTE --> SCANNER
    SSE_ADAPTER --> SCANNER
    
    SCANNER --> DETECTOR
    DETECTOR --> PROBER
    
    SCANNER -.-> MODELS
    DETECTOR -.-> MODELS
    PROBER -.-> MODELS
    
    style CLI fill:#e1f5fe
    style MCP fill:#f3e5f5
    style HTTP fill:#e8f5e8
    style SSE fill:#fff3e0
    
    style SCANNER fill:#ffebee
    style DETECTOR fill:#f1f8e9
    style PROBER fill:#e3f2fd
    style MODELS fill:#fafafa

分層掃描邏輯

flowchart TD
    START([開始掃描]) --> COMMON[🔍 常用端口掃描<br/>Top 1000 ports]
    COMMON --> CHECK{開放端口數量?}
    
    CHECK -->|< 3個端口| FULL[🔍 全端口深度掃描<br/>1-65535 ports<br/>可能有隱藏服務]
    CHECK -->|≥ 3個端口| SKIP[⏭️ 跳過全端口掃描<br/>已獲得足夠信息]
    
    FULL --> HTTP[🔎 HTTP服務檢測<br/>識別Web服務]
    SKIP --> HTTP
    
    HTTP --> WEB{發現Web服務?}
    WEB -->|是| PROBE[🕵️ Web深度探測<br/>• 目錄掃描<br/>• 管理後臺發現<br/>• 技術棧識別]
    WEB -->|否| RESULT
    
    PROBE --> RESULT[📊 輸出掃描結果]
    
    style START fill:#e3f2fd
    style COMMON fill:#f3e5f5
    style CHECK fill:#fff3e0
    style FULL fill:#ffebee
    style SKIP fill:#e8f5e8
    style HTTP fill:#f1f8e9
    style WEB fill:#fff3e0
    style PROBE fill:#e1f5fe
    style RESULT fill:#fafafa

💻 使用示例

基礎用法

# 掃描單個目標
python -m mcp_port_scanner scan 192.168.1.1

# 掃描指定端口
python -m mcp_port_scanner scan 192.168.1.1 -p 80,443,8080

# 批量掃描
python -m mcp_port_scanner batch 192.168.1.1 192.168.1.2 192.168.1.3

高級用法

MCP Server模式

MCP工具集

1. scan_target - 智能單目標掃描
   • 參數：ip(必需), ports(可選), scan_layers(可選), config(可選)
2. batch_scan - 批量掃描
   • 參數：targets(必需), scan_layers(可選), max_concurrent(可選)
3. get_scan_status - 查詢掃描狀態
   • 參數：scan_id(必需)
4. list_active_scans - 列出活躍掃描
   • 參數：無
5. get_scan_result - 獲取掃描結果
   • 參數：scan_id(必需)

配置 MCP Client

stdio模式（推薦本地使用）： Docker環境：

{
  "mcpServers": {
    "port-scanner-stdio": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-port-scanner", "python", "-m", "mcp_port_scanner.interfaces.mcp_local_server"],
      "description": "新版本MCP服務器 - 7個工具，智能掃描策略"
    }
  }
}

本地Python環境：

{
  "mcpServers": {
    "port-scanner-local": {
      "command": "python",
      "args": ["-m", "mcp_port_scanner.interfaces.mcp_local_server"],
      "cwd": "/path/to/mcp-port-scanner",
      "env": {
        "PYTHONPATH": "src"
      },
      "description": "本地新版本MCP服務器"
    }
  }
}

SSE模式（支持遠程訪問）：

{
  "mcpServers": {
    "port-scanner-remote": {
      "url": "http://YOUR_SERVER_IP:3000/mcp"
    }
  }
}

推薦使用 prompt.md 作為AI助手的系統提示詞，獲得專業的網絡安全分析能力。

Python SDK

from mcp_port_scanner import PortScannerSDK

# 創建實例
sdk = PortScannerSDK()

# 掃描目標
result = sdk.scan("192.168.1.1")
print(f"發現 {len(result.open_ports)} 個開放端口")
print(f"發現 {len(result.http_services)} 個Web服務")
print(f"發現 {len(result.admin_directories)} 個管理界面")

實際使用示例

單目標掃描：

請掃描 8.8.8.8，進行全面的安全分析

批量掃描：

批量掃描以下目標：
- 8.8.8.8
- www.producthunt.com
- 192.168.2.229

應急響應：

緊急掃描 192.168.2.229，懷疑有異常服務

Cursor + Docker 集成示例

以下是使用 Cursor 作為 MCP 客戶端，與通過 Docker 運行的掃描器服務進行交互的實際工作流程。 1. 快速掃描常用端口 2. 發現開放端口後的智能分析 3. 深入探測Web服務和管理後臺

📊 性能指標

📚 詳細文檔

• 📘 快速開始指南 - 5分鐘上手教程
• 📗 開發文檔 - 架構設計與擴展開發
• 📙 API參考 - 詳細的API文檔和示例
• 📕 架構設計 - 深入瞭解設計理念
• 📓 MCP SSE配置 - SSE傳輸模式配置指南
• 📔 Cursor配置 - Cursor編輯器集成指南

🛡️ 安全說明

⚠️ 重要提示

• 僅在授權的網絡環境中使用。
• 遵守當地法律法規。
• 合理控制掃描頻率。
• 不記錄敏感信息。

🤝 貢獻指南

我們歡迎並感謝社區的貢獻。請參考貢獻指南來幫助改進項目。

📄 許可證

本項目採用MIT許可證 - 查看 LICENSE 文件瞭解詳情。

🙏 致謝

• RustScan - 超快的端口掃描器
• MCP - Model Context Protocol
• FastAPI - 現代Web框架