Nmap Mcpserver

🚀 Nmap MCP Server

This is a server based on the Model Control Protocol (MCP), providing access to the nmap network scanning functionality.

✨ Features

• Run nmap scans with customizable options on specified targets.
• Store and retrieve scan results.
• Analyze scan results using AI prompts.

📦 Installation

Requirements:

• Python 3.10+
• python-libnmap
• nmap installed on the system

pip install python-libnmap

Ensure nmap is installed on the system:

# On Debian/Ubuntu
sudo apt-get install nmap

# On Fedora/CentOS
sudo dnf install nmap

💻 Usage Examples

Basic Usage

Run the server

Run the server directly from the source code:

python -m src.nmap_mcp

Run it as a command after installing the package:

pip install -e .
nmap-mcp

Available tools

1. run-nmap-scan
   • Run an nmap scan on the specified target.
   • Parameters:
     • target: Target host or network (e.g., 192.168.1.1 or 192.168.1.0/24).
     • options: nmap options (e.g., -sV -p 1-1000).
2. get-scan-details
   • Get detailed information about a specific scan.
   • Parameters:
     • scan_id: The ID of the scan to retrieve.
3. list-all-scans
   • List all available scan results.
   • No parameters required.

Available prompts

1. analyze-scan
   • Analyze nmap scan results.
   • Parameters:
     • scan_id: The ID of the scan to analyze.
     • focus: Analysis focus (security/services/overview).

Resources

Scan results are available as resources with the nmap://scan/{scan_id} URI scheme.

Advanced Usage

Example workflow

1. Run a scan:

Invoke tool: run-nmap-scan
Parameters: {"target": "192.168.1.0/24", "options": "-sV -p 22,80,443"}

2. Get scan details:

Invoke tool: get-scan-details
Parameters: {"scan_id": "<scan_id from the previous step>"}

3. List all scans:

Invoke tool: list-all-scans

4. Analyze scan results:

Get prompt: analyze-scan
Parameters: {"scan_id": "<scan_id>", "focus": "security"}

📚 Documentation

Security Considerations

This server executes nmap commands on your system. Be cautious when scanning networks you do not own or have permission for, as unauthorized scanning may be illegal in some jurisdictions.

Troubleshooting

If you encounter errors related to nmap not being found or execution errors:

1. Ensure nmap is installed and available in the PATH.
2. Check the logs to see the nmap executable being used.
3. The server will attempt to use the full nmap path to avoid conflicts.

Docker Usage

You can run the MCP server in a Docker container:

# Build the Docker image
docker build -t nmap-mcp-server .

# Run the Docker container
docker run -it --rm nmap-mcp-server

Integrated with the Glama MCP directory, the Docker container allows others to easily use this MCP server without worrying about installing dependencies.

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for details.