MCP Port Scanner

🚀 MCP Intelligent Port Scanner

Intelligent hierarchical port scanning service based on the MCP protocol, designed for AI assistants and development tools.

✨ Features

Intelligent Hierarchical Scanning

• 🧠 Dynamic Decision-making: Automatically adjust the scanning depth according to the number of ports, balancing efficiency and coverage.
• 🎯 Three-layer Architecture: Port scanning → HTTP detection → Web deep probing, delving deeper layer by layer.
• ⚡ Blazing-fast Performance: Based on RustScan, it's 10 times faster than traditional scanners.

Multiple Interface Support

• 🔌 MCP Protocol: Natively supports both stdio and HTTP/SSE transmission modes.
• 📊 Real-time Feedback: Push progress via SSE to visualize the scanning process.
• 🤖 AI Integration: Seamlessly integrate with AI tools like Cursor.

Use Cases

• Security Audits: Quickly discover network assets and potential risks.
• Operation and Maintenance Monitoring: Regularly scan infrastructure to ensure normal service operation.
• Development and Testing: Verify port configurations and service deployments.
• AI-assisted Analysis: Achieve intelligent security analysis through the MCP protocol.

🏗️ Architecture Design

System Architecture

graph TB
    subgraph "Interface Layer (Interfaces)"
        CLI["🖥️ CLI<br/>Command-line Interface"]
        MCP["🔌 MCP<br/>Protocol Interface"]
        HTTP["🌐 HTTP<br/>Web Interface"]
        SSE["📡 Cursor SSE<br/>Real-time Push"]
    end
    
    subgraph "Adapter Layer (Adapters)"
        CLI_ADAPTER["CLI Adapter"]
        MCP_LOCAL["MCP Local Adapter"]
        MCP_REMOTE["MCP Remote Adapter"]
        SSE_ADAPTER["SSE Adapter"]
    end
    
    subgraph "Service Layer (Service Layer)"
        SCANNER["🔍 Scanner<br/>Port Scanner"]
        DETECTOR["🔎 Detector<br/>HTTP Detector"]
        PROBER["🕵️ Prober<br/>Web Prober"]
        MODELS["📊 Models<br/>Data Models"]
    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

Hierarchical Scanning Logic

flowchart TD
    START([Start Scanning]) --> COMMON[🔍 Common Port Scanning<br/>Top 1000 ports]
    COMMON --> CHECK{Number of Open Ports?}
    
    CHECK -->|< 3 ports| FULL[🔍 Full Port Deep Scanning<br/>1-65535 ports<br/>May have hidden services]
    CHECK -->|≥ 3 ports| SKIP[⏭️ Skip Full Port Scanning<br/>Enough information obtained]
    
    FULL --> HTTP[🔎 HTTP Service Detection<br/>Identify Web Services]
    SKIP --> HTTP
    
    HTTP --> WEB{Web Service Found?}
    WEB -->|Yes| PROBE[🕵️ Web Deep Probing<br/>• Directory Scanning<br/>• Admin Panel Discovery<br/>• Technology Stack Identification]
    WEB -->|No| RESULT
    
    PROBE --> RESULT[📊 Output Scanning Results]
    
    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

🚀 Quick Start

Environment Preparation

# Clone the project
git clone https://github.com/relaxcloud-cn/port-scanner.git
cd mcp-port-scanner

# Install Python dependencies
pip install -r requirements.txt
pip install mcp

# Install RustScan (Required)
# 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

Quick Start with Docker

# Start the stdio mode service (for local Cursor integration)
docker-compose up -d mcp-port-scanner

# Start the SSE mode service (supports remote access)
docker-compose up -d mcp-port-scanner-sse

# Check the service status
docker-compose ps

💻 Usage Examples

1. Command-line Mode

# Scan a single target
python -m mcp_port_scanner scan 192.168.1.1

# Scan specified ports
python -m mcp_port_scanner scan 192.168.1.1 -p 80,443,8080

# Batch scan
python -m mcp_port_scanner batch 192.168.1.1 192.168.1.2 192.168.1.3

2. MCP Server Mode

MCP Toolset

1. scan_target - Intelligent single-target scanning

   • Parameters: ip (required), ports (optional), scan_layers (optional), config (optional)

2. batch_scan - Batch scanning

   • Parameters: targets (required), scan_layers (optional), max_concurrent (optional)

3. get_scan_status - Query the scanning status

   • Parameters: scan_id (required)

4. list_active_scans - List active scans

   • Parameters: None

5. get_scan_result - Get the scanning result

   • Parameters: scan_id (required)

Configure the MCP Client

stdio mode (recommended for local use):

Docker environment:

{
  "mcpServers": {
    "port-scanner-stdio": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-port-scanner", "python", "-m", "mcp_port_scanner.interfaces.mcp_local_server"],
      "description": "New version MCP server - 7 tools, intelligent scanning strategy"
    }
  }
}

Local Python environment:

{
  "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": "Local new version MCP server"
    }
  }
}

SSE mode (supports remote access):

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

It is recommended to use prompt.md as the system prompt for the AI assistant to obtain professional network security analysis capabilities.

3. Python SDK

from mcp_port_scanner import PortScannerSDK

# Create an instance
sdk = PortScannerSDK()

# Scan a target
result = sdk.scan("192.168.1.1")
print(f"Found {len(result.open_ports)} open ports")
print(f"Found {len(result.http_services)} web services")
print(f"Found {len(result.admin_directories)} admin panels")

Usage Examples

Single-target scanning:

Please scan 8.8.8.8 for a comprehensive security analysis.

Batch scanning:

Batch scan the following targets:
- 8.8.8.8
- www.producthunt.com
- 192.168.2.229

Emergency response:

Urgent scan of 192.168.2.229, suspecting abnormal services.

Cursor + Docker Integration Example

The following is the actual workflow of using Cursor as the MCP client to interact with the scanner service running through Docker.

1. Quick scan of common ports

2. Intelligent analysis after finding open ports

3. In-depth probing of Web services and admin panels

🎯 Performance Metrics

📚 Documentation

• 📘 Quick Start Guide - A 5-minute getting started tutorial
• 📗 Development Guide - Architecture design and extended development
• 📙 API Reference - Detailed API documentation and examples
• 📕 Architecture Design - In-depth understanding of the design concept
• 📓 MCP SSE Setup - Configuration guide for the SSE transmission mode
• 📔 Cursor Setup - Integration guide for the Cursor editor

⚠️ Important Note

• Only use in an authorized network environment.
• Comply with local laws and regulations.
• Reasonably control the scanning frequency.
• Do not record sensitive information.

🤝 Contribution Guide

We welcome and appreciate contributions from the community. Please refer to the Contribution Guide to help improve the project.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• RustScan - An ultra-fast port scanner
• MCP - Model Context Protocol
• FastAPI - A modern Web framework