houdin-mcp

Houdin MCP Server

MCP (Model Context Protocol) server for the Houdin threat intelligence platform. This enables AI assistants like Claude, Cursor, and others to autonomously investigate cyber threats by launching scans and retrieving results.

Requirements

This MCP server requires Bun runtime.

# Install Bun (macOS, Linux, WSL)
curl -fsSL https://bun.sh/install | bash

Features

• Launch scans on IPs, domains, URLs, file hashes, and email addresses
• Retrieve scan results from multiple threat intelligence sources (VirusTotal, AbuseIPDB, URLScan, etc.)
• Browse scan history with filtering and search
• View investigation trees created in the Houdin web interface

Installation

Using bunx (Recommended)

No installation required - just configure your MCP client:

bunx --bun houdin-mcp

Global Installation

npm install -g houdin-mcp
# or
bun install -g houdin-mcp

Configuration

Environment Variables

Variable	Required	Description
HOUDIN_API_KEY	Yes	Your Houdin API key (get from dashboard)
HOUDIN_API_URL	No	API base URL (default: https://houdin.io)
HOUDIN_TRANSPORT	No	Transport type: stdio (default) or http
HOUDIN_HTTP_PORT	No	Port for HTTP transport (default: 3001)

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
	"mcpServers": {
		"houdin": {
			"command": "bunx",
			"args": ["--bun", "houdin-mcp"],
			"env": {
				"HOUDIN_API_KEY": "your-api-key-here"
			}
		}
	}
}

Cursor

Add to your Cursor MCP settings:

{
	"mcpServers": {
		"houdin": {
			"command": "bunx",
			"args": ["--bun", "houdin-mcp"],
			"env": {
				"HOUDIN_API_KEY": "your-api-key-here"
			}
		}
	}
}

HTTP Mode (Remote Server)

For remote access or web integrations:

HOUDIN_TRANSPORT=http HOUDIN_API_KEY=your-key bunx --bun houdin-mcp

This starts an HTTP server at http://localhost:3001/mcp. Authenticate with:

Authorization: Bearer <your-api-key>

Available Tools

launch_scan

Launch a threat intelligence scan on an indicator of compromise (IOC).

Parameters:

• artifact (required): The IOC to scan (IP, domain, URL, hash, or email)
• scanners (optional): Array of specific scanners to use
• forceRescan (optional): Skip cache and force fresh scan

Example prompt:

Scan the IP address 8.8.8.8 for threat intelligence

get_scan_results

Retrieve complete results from a scan. Automatically waits for completion if scan is still in progress.

Parameters:

• scanID (required): The scan ID from launch_scan
• timeout (optional): Max seconds to wait (default: 70)
• pollInterval (optional): Seconds between status checks (default: 3)

Example prompt:

Get the results for scan houdin-abc123

get_scan_history

List recent scans with optional filtering.

Parameters:

• searchTerm (optional): Filter by artifact or scan ID
• limit (optional): Max results (default: 10, max: 50)
• iocTypes (optional): Filter by IOC types
• sortOrder (optional): asc or desc (default: desc)

Example prompt:

Show my last 5 scans for domain IOCs

get_investigation_tree

Get the hierarchical tree of a multi-scan investigation (created in the Houdin web interface).

Parameters:

• scanID (required): Any scan ID in the tree

Example prompt:

Show the investigation tree for scan houdin-abc123

Workflow Example

User: Scan the domain suspicious-site.com for threat intelligence

AI: I'll scan that domain for you.
[Uses launch_scan with artifact="suspicious-site.com"]

AI: The scan has been launched. Let me get the results.
[Uses get_scan_results with the returned scanID]

AI: Here's what I found:
- VirusTotal: 3/90 vendors flagged this as malicious
- AbuseIPDB: Confidence score of 45%
- The domain resolves to IP 192.168.1.1
- Mesmer AI analysis indicates moderate risk (score: 6/10)

Would you like me to scan any of the related indicators found?