README.md•6.33 kB
# 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:**
```bash
brew install nmap
```
**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install nmap
```
**CentOS/RHEL:**
```bash
sudo yum install nmap
# or for newer versions:
sudo dnf install nmap
```
**Windows:**
Download and install from [nmap.org](https://nmap.org/download.html)
## Installation
1. Clone this repository:
```bash
git clone <repository-url>
cd nmap-mcp-server
```
2. Install dependencies:
```bash
pip install -e .
```
## Usage
### Running the FastMCP Server
The server can be run directly with stdio transport:
```bash
python server.py
```
Or using the installed script:
```bash
nmap-mcp-server
```
### Claude Desktop Configuration
Add the following configuration to your Claude Desktop MCP settings:
```json
{
"mcpServers": {
"NmapMCP": {
"command": "uv",
"args": [
"--directory",
"/Users/haji/mcp-servers/nmap-mcp-server",
"run",
"server.py"
]
}
}
}
```
**Configuration Steps:**
1. Open Claude Desktop
2. Go to Settings → MCP Servers
3. Add the JSON configuration above
4. Restart Claude Desktop
5. Verify the server is connected
## FastMCP Tool Examples
### Basic Network Scan
```python
# The tool is called with typed parameters
result = await nmap_basic_scan(
targets="192.168.1.0/24",
ports="common",
scan_type="quick"
)
```
### Service Detection
```python
result = await nmap_service_detection(
targets="example.com",
ports="80,443,8080",
intensity=7
)
```
### Vulnerability Assessment
```python
result = await nmap_vulnerability_scan(
targets="192.168.1.100",
ports="common",
vuln_category="all"
)
```
### Custom Scan
```python
result = await nmap_custom_scan(
targets="example.com",
custom_options="-sS -p 1-1000 -A --script=vuln",
output_format="normal"
)
```
## FastMCP Architecture
The server uses FastMCP's clean decorator pattern:
```python
@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."""
# Implementation here
return result
```
## Security Considerations
⚠️ **Important Security Notes:**
1. **Legal Compliance**: Only scan networks and systems you own or have explicit permission to scan.
2. **Network Impact**: Some scans can be resource-intensive and may impact network performance.
3. **Detection**: Aggressive scans may trigger security systems and firewalls.
4. **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:
```bash
# Test tool registration and functionality
python test_fastmcp.py
# Test examples
python example_usage.py
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. 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:
1. Check the error logs
2. Verify Nmap is installed and accessible
3. Ensure you have proper permissions
4. 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