MCP Port Scanner

🚀 MCP智能端口扫描器

基于MCP协议的智能分层端口扫描服务，专为AI助手和开发工具设计

🌟 核心特性

智能分层扫描

🧠 动态决策：根据端口数量自动调整扫描深度，平衡效率与覆盖率
🎯 三层架构：端口扫描 → HTTP检测 → Web深度探测，逐层深入
⚡ 极速性能：基于RustScan，比传统扫描器快10倍

多种接口支持

🔌 MCP协议：原生支持stdio和HTTP/SSE两种传输模式
📊 实时反馈：SSE推送进度，让扫描过程可视化
🤖 AI集成：与Cursor等AI工具无缝集成

适用场景

安全审计：快速发现网络资产和潜在风险
运维监控：定期扫描基础设施，确保服务正常
开发测试：验证端口配置和服务部署
AI辅助分析：通过MCP协议实现智能化安全分析

🏗️ 架构设计

系统架构

分层扫描逻辑

Docker快速启动

# 启动stdio模式服务（本地Cursor集成）
docker-compose up -d mcp-port-scanner

# 启动SSE模式服务（支持远程访问）
docker-compose up -d mcp-port-scanner-sse

# 查看服务状态
docker-compose ps

🛠️ 使用方式

1. 命令行模式

# 检查 RustScan 状态
python -m mcp_port_scanner.interfaces.cli_interface rustscan

# 扫描单个目标
python -m mcp_port_scanner.interfaces.cli_interface scan 192.168.1.1

# 扫描指定端口
python -m mcp_port_scanner.interfaces.cli_interface scan 192.168.1.1 -p 80,443,8080

# 批量扫描
python -m mcp_port_scanner.interfaces.cli_interface batch 192.168.1.1 192.168.1.2 192.168.1.3

# 查看帮助
python -m mcp_port_scanner.interfaces.cli_interface --help

2. MCP Server模式

MCP工具集

scan_target - 智能单目标扫描
- 参数：ip(必需), ports(可选), scan_layers(可选), config(可选)
batch_scan - 批量扫描
- 参数：targets(必需), scan_layers(可选), max_concurrent(可选)
get_scan_status - 查询扫描状态
- 参数：scan_id(必需)
list_active_scans - 列出活跃扫描
- 参数：无
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环境：

⚠️ 前置条件：
安装项目依赖：pip install -r requirements.txt
确保bin/目录下有对应平台的RustScan二进制文件
或系统已安装RustScan（sudo apt install rustscan 或 brew install rustscan）

{
  "mcpServers": {
    "port-scanner-local": {
      "command": "python",
      "args": ["-m", "mcp_port_scanner.interfaces.mcp_local_server"],
      "cwd": "./mcp-port-scanner",
      "env": {
        "PYTHONPATH": "src"
      },
      "description": "本地MCP服务器 - 7个工具，智能扫描策略"
    }
  }
}

路径配置说明：

推荐使用相对路径："./mcp-port-scanner"（相对于Cursor工作目录）
或使用绝对路径："/path/to/your/mcp-port-scanner"
Windows示例："C:/Users/YourName/Projects/mcp-port-scanner"

SSE模式（支持远程访问）：

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

📋 本地MCP Server快速验证

完成配置后，可以通过以下方式验证MCP服务器是否正常工作：

# 1. 切换到项目目录
cd ./mcp-port-scanner 

# 2. 设置环境变量
export PYTHONPATH=src  # Linux/macOS
# 或 Windows PowerShell：$env:PYTHONPATH="src"

# 3. 手动启动MCP服务器测试
python -m mcp_port_scanner.interfaces.mcp_local_server

# 4. 检查RustScan状态
python -c "from src.mcp_port_scanner.rustscan_manager import get_rustscan_manager; print(get_rustscan_manager().verify_rustscan())"

如果遇到问题：

确认依赖已安装：pip list | grep mcp
检查RustScan：bin/rustscan-windows-x64.exe --version（Windows）
查看日志：检查logs/目录下的日志文件

推荐使用 prompt.md 作为AI助手的系统提示词，获得专业的网络安全分析能力。

3. 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服务和管理后台

深度探测

🎯 性能指标

扫描类型	典型耗时	说明
快速扫描	84.28-230.5秒	仅常用端口
智能扫描（少端口）	30-60秒	包含全端口扫描
智能扫描（多端口）	88-202.37秒	没有全款端口扫描，所有扫描层级
完整扫描	655-951秒	全端口扫描，所有扫描层级
C段扫描	5-15分钟	254个IP地址

📖 文档

📘 快速开始指南 - 5分钟上手教程
📗 开发文档 - 架构设计与扩展开发
📙 API参考 - 详细的API文档和示例
📕 架构设计 - 深入了解设计理念
📓 MCP SSE配置 - SSE传输模式配置指南
📔 Cursor配置 - Cursor编辑器集成指南

🛡️ 安全说明

仅在授权的网络环境中使用
遵守当地法律法规
合理控制扫描频率
不记录敏感信息

🤝 贡献指南

我们欢迎并感谢社区的贡献。请参考贡献指南来帮助改进项目。

📄 许可证

本项目采用MIT许可证 - 查看 LICENSE 文件了解详情

🙏 致谢

RustScan - 超快的端口扫描器
MCP - Model Context Protocol
FastAPI - 现代Web框架

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

An intelligent layered port scanning service based on MCP protocol, designed for AI assistants and development tools to perform network security analysis with real-time feedback.

Related MCP Servers

MCP NMAP Server
PhialsBasement
-
security
A
license
-
quality
Enables AI assistants to perform network scanning operations using NMAP, offering a standardized interface for network analysis and security assessments through AI conversations.
Last updated -
250
25
JavaScript
MIT License
Nmap MCP Server
imjdl
A
security
A
license
A
quality
A Model Control Protocol server that provides access to nmap network scanning functionality, allowing users to run customizable scans, store results, and analyze network security using AI prompts.
Last updated -
3
7
Python
MIT License
HydraΜCP
HappyHackingSpace
-
security
A
license
-
quality
A lightweight, extensible cybersecurity toolkit that connects AI assistants to security tools through the Model Context Protocol (MCP), enabling AI-assisted security research, scanning, and analysis.
Last updated -
7
Python
MIT License
Pentest Tools MCP Server
ch1nhpd
-
security
F
license
-
quality
An MCP server that integrates various penetration testing tools, enabling security professionals to perform reconnaissance, vulnerability scanning, and API testing through natural language commands in compatible LLM clients like Claude Desktop.
Last updated -
3
Python

View all related MCP servers