home / mcp / porthunter mcp server
Local MCP server that analyzes PCAP/PCAPNG captures, detects scan techniques, classifies patterns, lists suspects, and enriches IPs.
Configuration
View docs{
"mcpServers": {
"abysswalkr-porthunter-mcp": {
"command": "python",
"args": [
"-m",
"porthunter.server"
],
"env": {
"PORT_HUNTER_TOKEN": "TEST_TOKEN",
"PORT_HUNTER_ALLOWED_DIR": ". or current directory",
"PORT_HUNTER_MAX_PCAP_MB": "50",
"PORT_HUNTER_ALLOW_PRIVATE": "false",
"PORT_HUNTER_REQUIRE_TOKEN": "true"
}
}
}
}PortHunter MCP is a local MCP server that analyzes PCAP/PCAPNG captures, detects common scan techniques, classifies patterns, lists suspicious hosts, and enriches IPs with external data. It is designed to be consumed by any MCP host or chatbot, enabling you to quickly derive insights from network capture data and correlate findings across tools.
You run PortHunter as a local STDIO MCP server and connect to it from an MCP client. Start by launching the server with the required environment settings, then call the available tools to analyze captures, list suspects, retrieve the first scan event, enrich IPs, and perform correlation across IPs. The tools return structured results in UTC ISO-8601 timestamps, allowing you to build workflows that react to detected scanning patterns and enrichment data.
Prerequisites: Python 3.11 or newer, and a development environment for your operating system (Windows, Linux, or macOS). Optional: Docker can be used for containerized runs.
1) Create a virtual environment.
python -m venv .venv
# Windows PowerShell
# .\.venv\Scripts\Activate.ps1
# Linux/macOS
# source .venv/bin/activate2) Upgrade pip and install the package in editable mode so you can develop and test locally.
pip install -U pip
pip install -e .You run PortHunter in STDIO mode and feed it calls using an MCP client. Configure the environment with a token, access directory, and optional limits. The server will listen for IPC calls and return results in JSON.
# Windows Command Prompt
set PORT_HUNTER_TOKEN=TEST_TOKEN
set PORT_HUNTER_ALLOWED_DIR=%CD%
set PORT_HUNTER_REQUIRE_TOKEN=true
set PORT_HUNTER_MAX_PCAP_MB=50
python -m porthunter.server
```
```bash
# Linux/macOS
export PORT_HUNTER_TOKEN=TEST_TOKEN
export PORT_HUNTER_ALLOWED_DIR="$PWD"
export PORT_HUNTER_REQUIRE_TOKEN=true
export PORT_HUNTER_MAX_PCAP_MB=50
python -m porthunter.serverPortHunter exposes several tools you can call via the MCP client. Each tool runs with UTC timestamps for generated data and returns structured results.
- scan_overview: produces an overview of the capture including scanners, targets, and suspected patterns. Use this to get a high-level view of the activity in a PCAP.
- list_suspects: lists potential suspects with metrics like distinct ports and packet rate to help you prioritize investigations.
- first_scan_event: returns the first relevant event detected in the capture for quick context.
- enrich_ip: fetches enrichment data for a given IP, including ASN, organization, geographic location, and potential threat indicators from sources like OTX and GreyNoise.
- correlate: combines results across multiple IPs to assess relationships and produce a consolidated view.
Analyzes a PCAP/PCAPNG to provide an overview of scanners, targets, port hits, and suspected scan patterns.
Lists suspected IPs with metrics such as distinct ports and packet rate to help prioritize investigations.
Returns the first relevant scan event detected in the capture for quick context.
Fetches enrichment data for an IP, including ASN, organization, geo, and threat indicators from external sources.
Combines results across multiple IPs to provide a consolidated view and cross-IP insights.