Supports installation and operation on CentOS systems with specific yum/dnf package manager instructions for setting up the required Nmap dependencies.
Supports installation and operation on Debian systems with specific apt package manager instructions for setting up the required Nmap dependencies.
Supports installation and operation on macOS systems through Homebrew package manager, with specific configuration instructions for macOS environments.
Leverages Python for implementation with specific version requirements (Python 3.10+) and dependency management through pip.
Supports installation and operation on Ubuntu systems with specific apt package manager instructions for setting up the required Nmap dependencies.
Nmap MCP Server
A Model Context Protocol (MCP) server that exposes Nmap CLI functionality as MCP tools using FastMCP with stdio transport. This server provides comprehensive network scanning capabilities through the Nmap command-line tool.
š FastMCP Implementation
This server is built using FastMCP, a modern, high-performance MCP framework that provides:
Simplified API: Clean decorator-based tool registration
Type Safety: Full type hints and validation
Stdio Transport: Efficient communication via standard input/output
Async Support: Non-blocking operations with proper error handling
Features
The Nmap MCP Server exposes the following tools using FastMCP decorators:
1. Basic Scan (nmap_basic_scan
)
Perform basic Nmap scans with different intensity levels:
Quick: Fast scan with high throughput
Comprehensive: Full scan with service detection and OS detection
Stealth: Low-profile scan to avoid detection
2. Service Detection (nmap_service_detection
)
Detect services and versions running on target hosts with configurable intensity levels (0-9).
3. OS Detection (nmap_os_detection
)
Detect operating systems running on target hosts with configurable retry attempts.
4. Script Scanning (nmap_script_scan
)
Run NSE (Nmap Scripting Engine) scripts for advanced reconnaissance and vulnerability assessment.
5. Stealth Scan (nmap_stealth_scan
)
Perform SYN scans with minimal detection using configurable timing templates.
6. Comprehensive Scan (nmap_comprehensive_scan
)
Perform full-featured scans combining multiple detection methods.
7. Ping Scan (nmap_ping_scan
)
Discover live hosts using various ping methods (ICMP, TCP, or both).
8. Port Scan (nmap_port_scan
)
Scan specific ports using different methods (SYN, Connect, UDP).
9. Vulnerability Scan (nmap_vulnerability_scan
)
Run vulnerability detection scripts with different categories.
10. Network Discovery (nmap_network_discovery
)
Discover hosts and services on entire networks.
11. Custom Scan (nmap_custom_scan
)
Perform scans with user-defined Nmap options for maximum flexibility.
Prerequisites
Python 3.10 or higher
Nmap installed and available in your system PATH
Installing Nmap
macOS:
Ubuntu/Debian:
CentOS/RHEL:
Windows: Download and install from nmap.org
Installation
Clone this repository:
Install dependencies:
Usage
Running the FastMCP Server
The server can be run directly with stdio transport:
Or using the installed script:
Claude Desktop Configuration
Add the following configuration to your Claude Desktop MCP settings:
Configuration Steps:
Open Claude Desktop
Go to Settings ā MCP Servers
Add the JSON configuration above
Restart Claude Desktop
Verify the server is connected
FastMCP Tool Examples
Basic Network Scan
Service Detection
Vulnerability Assessment
Custom Scan
FastMCP Architecture
The server uses FastMCP's clean decorator pattern:
Security Considerations
ā ļø Important Security Notes:
Legal Compliance: Only scan networks and systems you own or have explicit permission to scan.
Network Impact: Some scans can be resource-intensive and may impact network performance.
Detection: Aggressive scans may trigger security systems and firewalls.
Rate Limiting: The server includes timeouts and rate limiting to prevent abuse.
Error Handling
The FastMCP server includes comprehensive error handling for:
Nmap command not found
Command timeouts
Invalid arguments
Network connectivity issues
Permission errors
Logging
The server uses Python's built-in logging system. Logs include:
Command execution details
Error messages
Performance metrics
Testing
Test the FastMCP server:
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Disclaimer
This tool is for educational and authorized security testing purposes only. Users are responsible for ensuring they have proper authorization before scanning any network or system.
Support
For issues and questions:
Check the error logs
Verify Nmap is installed and accessible
Ensure you have proper permissions
Open an issue on the repository
Changelog
Version 1.0.0
Initial release with FastMCP implementation
Support for all major Nmap scanning techniques
Comprehensive error handling
Stdio transport mode
Type-safe tool definitions
Claude Desktop configuration with uv
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
Exposes Nmap network scanning capabilities through a Model Context Protocol (MCP) server, allowing users to perform various types of network scans including vulnerability assessment, service detection, and OS fingerprinting.
- š FastMCP Implementation
- Features
- 1. Basic Scan (nmap_basic_scan)
- 2. Service Detection (nmap_service_detection)
- 3. OS Detection (nmap_os_detection)
- 4. Script Scanning (nmap_script_scan)
- 5. Stealth Scan (nmap_stealth_scan)
- 6. Comprehensive Scan (nmap_comprehensive_scan)
- 7. Ping Scan (nmap_ping_scan)
- 8. Port Scan (nmap_port_scan)
- 9. Vulnerability Scan (nmap_vulnerability_scan)
- 10. Network Discovery (nmap_network_discovery)
- 11. Custom Scan (nmap_custom_scan)
- Prerequisites
- Installation
- Usage
- FastMCP Tool Examples
- FastMCP Architecture
- Security Considerations
- Error Handling
- Logging
- Testing
- Contributing
- License
- Disclaimer
- Support
- Changelog
Related MCP Servers
- -securityAlicense-qualityEnables AI assistants to perform network scanning operations using NMAP, offering a standardized interface for network analysis and security assessments through AI conversations.Last updated -2433MIT License
- -securityAlicense-qualityMCP Server provides a simpler API to interact with the Model Context Protocol by allowing users to define custom tools and services to streamline workflows and processes.Last updated -63MIT License
Semgrep MCP Serverofficial
AsecurityAlicenseAqualityAn MCP server that provides a comprehensive interface to Semgrep, enabling users to scan code for security vulnerabilities, create custom rules, and analyze scan results through the Model Context Protocol.Last updated -6579MIT License- -securityAlicense-qualityMCP Server for networl monitoring software ntopng.Last updated -MIT License