Nmap MCP Server

🚀 Nmap MCP 服務器

Nmap MCP 服務器是一個模型上下文協議（MCP）服務器，它使用 FastMCP 和標準輸入輸出（stdio）傳輸方式，將 Nmap 命令行工具的功能以 MCP 工具的形式暴露出來。該服務器通過 Nmap 命令行工具提供了全面的網絡掃描能力。

🚀 快速開始

FastMCP 實現

本服務器基於 FastMCP 構建，這是一個現代、高性能的 MCP 框架，具備以下特點：

• 簡化的 API：基於裝飾器的簡潔工具註冊方式
• 類型安全：完整的類型提示和驗證
• 標準輸入輸出傳輸：通過標準輸入輸出實現高效通信
• 異步支持：支持非阻塞操作並具備完善的錯誤處理機制

✨ 主要特性

Nmap MCP 服務器使用 FastMCP 裝飾器暴露了以下工具：

1. 基礎掃描 (nmap_basic_scan)

可執行不同強度級別的基礎 Nmap 掃描：

• 快速掃描：高吞吐量的快速掃描
• 全面掃描：包含服務檢測和操作系統檢測的完整掃描
• 隱身掃描：低特徵掃描，避免被檢測

2. 服務檢測 (nmap_service_detection)

檢測目標主機上運行的服務和版本，強度級別可配置（0 - 9）。

3. 操作系統檢測 (nmap_os_detection)

檢測目標主機上運行的操作系統，重試次數可配置。

4. 腳本掃描 (nmap_script_scan)

運行 NSE（Nmap 腳本引擎）腳本，用於高級偵察和漏洞評估。

5. 隱身掃描 (nmap_stealth_scan)

使用可配置的計時模板執行 SYN 掃描，儘量減少被檢測的風險。

6. 全面掃描 (nmap_comprehensive_scan)

結合多種檢測方法執行全功能掃描。

7. ping 掃描 (nmap_ping_scan)

使用各種 ping 方法（ICMP、TCP 或兩者結合）發現存活主機。

8. 端口掃描 (nmap_port_scan)

使用不同方法（SYN、Connect、UDP）掃描特定端口。

9. 漏洞掃描 (nmap_vulnerability_scan)

運行不同類別的漏洞檢測腳本。

10. 網絡發現 (nmap_network_discovery)

發現整個網絡中的主機和服務。

11. 自定義掃描 (nmap_custom_scan)

使用用戶定義的 Nmap 選項進行掃描，提供最大的靈活性。

📦 安裝指南

前提條件

• Python 3.10 或更高版本
• 系統 PATH 中已安裝並可訪問 Nmap

安裝 Nmap

macOS：

brew install nmap

Ubuntu/Debian：

sudo apt update
sudo apt install nmap

CentOS/RHEL：

sudo yum install nmap
# 或對於較新版本：
sudo dnf install nmap

Windows： 從 nmap.org 下載並安裝。

安裝步驟

1. 克隆本倉庫：

git clone <repository-url>
cd nmap-mcp-server

2. 安裝依賴：

pip install -e .

💻 使用示例

運行 FastMCP 服務器

可直接使用標準輸入輸出傳輸方式運行服務器：

python server.py

或者使用已安裝的腳本：

nmap-mcp-server

Claude Desktop 配置

在 Claude Desktop MCP 設置中添加以下配置：

{
  "mcpServers": {
    "NmapMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/haji/mcp-servers/nmap-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

配置步驟：

1. 打開 Claude Desktop
2. 轉到設置 → MCP 服務器
3. 添加上述 JSON 配置
4. 重啟 Claude Desktop
5. 驗證服務器是否已連接

基礎用法

基礎網絡掃描

# 該工具調用時使用了類型化參數
result = await nmap_basic_scan(
    targets="192.168.1.0/24",
    ports="common",
    scan_type="quick"
)

服務檢測

result = await nmap_service_detection(
    targets="example.com",
    ports="80,443,8080",
    intensity=7
)

漏洞評估

result = await nmap_vulnerability_scan(
    targets="192.168.1.100",
    ports="common",
    vuln_category="all"
)

自定義掃描

result = await nmap_custom_scan(
    targets="example.com",
    custom_options="-sS -p 1-1000 -A --script=vuln",
    output_format="normal"
)

高級用法

FastMCP 架構

服務器使用了 FastMCP 的簡潔裝飾器模式：

@app.tool(
    name="nmap_basic_scan",
    description="Perform a basic Nmap scan of specified targets"
)
async def nmap_basic_scan(
    targets: str,
    ports: str = "common",
    scan_type: str = "quick"
) -> str:
    """Perform a basic Nmap scan of specified targets."""
    # 此處為實現代碼
    return result

📚 詳細文檔

安全注意事項

⚠️ 重要安全提示

1. 法律合規：僅掃描您擁有或獲得明確授權的網絡和系統。
2. 網絡影響：某些掃描可能會佔用大量資源，影響網絡性能。
3. 檢測風險：激進的掃描可能觸發安全系統和防火牆。
4. 速率限制：服務器包含超時和速率限制，以防止濫用。

錯誤處理

FastMCP 服務器包含全面的錯誤處理機制，用於處理以下情況：

• Nmap 命令未找到
• 命令超時
• 參數無效
• 網絡連接問題
• 權限錯誤

日誌記錄

服務器使用 Python 內置的日誌系統，日誌包括：

• 命令執行細節
• 錯誤消息
• 性能指標

測試

測試 FastMCP 服務器：

# 測試工具註冊和功能
python test_fastmcp.py

# 測試示例
python example_usage.py

貢獻代碼

1. 分叉倉庫
2. 創建功能分支
3. 進行修改
4. 如有必要，添加測試
5. 提交拉取請求

許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

免責聲明

本工具僅用於教育和授權的安全測試目的。用戶在掃描任何網絡或系統之前，有責任確保獲得了適當的授權。

支持

遇到問題或有疑問時：

1. 檢查錯誤日誌
2. 驗證 Nmap 是否已安裝並可訪問
3. 確保您擁有適當的權限
4. 在倉庫中創建一個問題

變更日誌

版本 1.0.0

• 首次發佈，實現 FastMCP
• 支持所有主要的 Nmap 掃描技術
• 全面的錯誤處理
• 標準輸入輸出傳輸模式
• 類型安全的工具定義
• 使用 uv 進行 Claude Desktop 配置