Bettercap MCP Server

HIGHEST RISK MCP server providing passive network reconnaissance capabilities via bettercap.

Security Notice

This is a HIGHEST RISK tool with the strongest security controls in place:

• Root privileges required for all operations
• Explicit authorization required - Must set authorized: true for every operation
• Attack modules BLOCKED - Spoofing, proxies, injection, and all offensive modules are disabled
• Passive reconnaissance only - Only monitoring and discovery capabilities enabled
• Duration limits enforced - Maximum 120 seconds per operation (60s for packet sniffing)
• API access restricted - Only localhost/127.0.0.1 connections allowed

Blocked Modules (Offensive/Attack)

The following modules are COMPLETELY BLOCKED for security:

• arp.spoof - ARP spoofing attacks
• dns.spoof - DNS spoofing attacks
• dhcp6.spoof - DHCPv6 spoofing attacks
• packet.proxy - Packet manipulation proxy
• tcp.proxy - TCP proxy
• http.proxy - HTTP proxy (reading logs is allowed)
• https.proxy - HTTPS proxy
• any.proxy - Generic proxy
• mac.changer - MAC address changing
• hid - HID emulation attacks
• gps - GPS spoofing

Allowed Modules (Passive Only)

Only the following passive reconnaissance modules are allowed:

• net.recon - Network host discovery
• net.probe - Network probing
• net.sniff - Passive packet capture
• wifi.recon - WiFi access point discovery
• ble.recon - Bluetooth Low Energy scanning
• events.stream - Event monitoring

Prerequisites

1. Install bettercap

macOS:

brew install bettercap

Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install bettercap

Linux (Arch):

sudo pacman -S bettercap

From source:

go install github.com/bettercap/bettercap@latest

2. Root Privileges

All bettercap operations require root/sudo privileges:

# Run with sudo
sudo bun run start

# Or run as root
sudo -i
bun run start

3. Network Interfaces

Ensure you have appropriate network interfaces:

• Ethernet/WiFi: For network reconnaissance (net.recon)
• WiFi with monitor mode: For WiFi scanning (wifi.recon)
• Bluetooth adapter: For BLE scanning (ble.recon)

Check available interfaces:

ip link show        # Linux
ifconfig            # macOS/BSD

Installation

cd bettercap
bun install

Usage

Start the Server

# With root privileges
sudo bun run start

# Or build and run
bun run build
sudo node dist/index.js

Configure in Claude Desktop

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

{
  "mcpServers": {
    "bettercap": {
      "command": "sudo",
      "args": [
        "bun",
        "run",
        "/path/to/mi-mcp-servers/packages/bettercap/src/index.ts"
      ],
      "env": {
        "BETTERCAP_API_URL": "http://127.0.0.1:8081",
        "BETTERCAP_API_USER": "user",
        "BETTERCAP_API_PASSWORD": "pass"
      }
    }
  }
}

Using API Mode (Optional)

For the bettercap_session_info tool, start bettercap with API server:

sudo bettercap -caplet http-ui

Set environment variables:

export BETTERCAP_API_URL="http://127.0.0.1:8081"
export BETTERCAP_API_USER="user"
export BETTERCAP_API_PASSWORD="pass"

Available Tools

1. bettercap_net_recon

Discover active hosts on the local network.

Parameters:

• authorized (boolean, required): Confirm authorization - must be true
• interface (string, optional): Network interface (e.g., eth0, wlan0)
• duration (number, default: 30): Scan duration in seconds (5-120)

Example:

{
  "authorized": true,
  "interface": "eth0",
  "duration": 60
}

Returns:

{
  "interface": "eth0",
  "hosts": [
    {
      "ip": "192.168.1.1",
      "mac": "aa:bb:cc:dd:ee:ff",
      "hostname": "router.local",
      "vendor": "Cisco",
      "first_seen": "2024-01-01T12:00:00Z",
      "last_seen": "2024-01-01T12:01:00Z"
    }
  ],
  "total_hosts": 15,
  "duration_seconds": 60
}

2. bettercap_wifi_scan

Scan for WiFi access points and clients.

Requirements:

• WiFi adapter with monitor mode support
• Root privileges

Parameters:

• authorized (boolean, required): Confirm authorization
• duration (number, default: 30): Scan duration (5-120)
• interface (string, optional): WiFi interface

Returns:

{
  "interface": "wlan0",
  "access_points": [
    {
      "ssid": "MyNetwork",
      "bssid": "aa:bb:cc:dd:ee:ff",
      "channel": 6,
      "encryption": "WPA2",
      "clients_count": 3,
      "rssi": -45,
      "vendor": "TP-Link"
    }
  ],
  "clients": [
    {
      "mac": "11:22:33:44:55:66",
      "bssid": "aa:bb:cc:dd:ee:ff",
      "rssi": -60,
      "vendor": "Apple"
    }
  ],
  "total_aps": 10,
  "total_clients": 15
}

3. bettercap_ble_scan

Scan for Bluetooth Low Energy devices.

Parameters:

• authorized (boolean, required): Confirm authorization
• duration (number, default: 30): Scan duration (5-120)

Returns:

{
  "devices": [
    {
      "mac": "aa:bb:cc:dd:ee:ff",
      "name": "Fitness Tracker",
      "vendor": "Fitbit",
      "rssi": -65,
      "connectable": true,
      "flags": ["LE_GENERAL"],
      "services": ["0000180d-0000-1000-8000-00805f9b34fb"]
    }
  ],
  "total_devices": 8
}

4. bettercap_http_proxy_log

Read existing HTTP proxy log files.

Note: Does NOT start a proxy (proxies are blocked). Only reads existing logs.

Parameters:

• authorized (boolean, required): Confirm authorization
• log_path (string, optional): Path to log file

Returns:

{
  "entries": [
    {
      "timestamp": "2024-01-01T12:00:00Z",
      "method": "GET",
      "url": "http://example.com/page",
      "status": 200,
      "content_type": "text/html",
      "source_ip": "192.168.1.100"
    }
  ],
  "total": 150
}

5. bettercap_net_sniff

Passive packet capture with BPF filtering.

Parameters:

• authorized (boolean, required): Confirm authorization
• duration (number, default: 15): Sniff duration (5-60, strictly limited)
• filter (string, optional): BPF filter expression
• interface (string, optional): Network interface

BPF Filter Examples:

• tcp port 80 - HTTP traffic
• udp - All UDP packets
• host 192.168.1.1 - Specific host
• tcp port 443 - HTTPS traffic

Returns:

{
  "interface": "eth0",
  "duration": 15,
  "packets": [
    {
      "timestamp": "12:00:00.123",
      "protocol": "TCP",
      "source": "192.168.1.100:54321",
      "destination": "93.184.216.34:80",
      "size": 1500,
      "info": "HTTP GET"
    }
  ],
  "total_packets": 245,
  "by_protocol": {
    "TCP": 180,
    "UDP": 50,
    "ICMP": 15
  }
}

6. bettercap_session_info

Get bettercap session information via API.

Requirements:

• Bettercap running with API: sudo bettercap -caplet http-ui
• API URL, user, and password configured

Parameters:

• authorized (boolean, required): Confirm authorization

Returns:

{
  "interface": "eth0",
  "gateway": "192.168.1.1",
  "started_at": "2024-01-01T12:00:00Z",
  "modules": [
    {
      "name": "net.recon",
      "running": true,
      "description": "Network reconnaissance module"
    }
  ],
  "env_vars": {
    "net.sniff.verbose": "true",
    "net.sniff.local": "false"
  },
  "version": "2.32.0"
}

Security Best Practices

1. Authorization

ALWAYS obtain proper authorization before scanning:

• Get written permission for network scanning
• Only scan networks you own or have permission to test
• Be aware of local laws and regulations
• Corporate networks may have security policies against scanning

2. Network Impact

Minimize network disruption:

• Use shorter duration scans when possible
• Avoid peak network hours
• Monitor network performance
• Stop if issues occur

3. Data Handling

Handle scan results responsibly:

• Don't share sensitive network information
• Store results securely
• Follow data protection regulations
• Delete when no longer needed

4. Legal Compliance

Understand legal implications:

• Unauthorized network scanning may be illegal
• Computer Fraud and Abuse Act (US)
• Computer Misuse Act (UK)
• Similar laws in other jurisdictions
• Corporate security policies

Troubleshooting

Permission Denied

# Ensure running with root
sudo bun run start

# Check file permissions
ls -la $(which bettercap)

Interface Not Found

# List interfaces
ip link show              # Linux
ifconfig                  # macOS

# Specify interface explicitly
{
  "authorized": true,
  "interface": "eth0"
}

WiFi Monitor Mode Issues

# Enable monitor mode (Linux)
sudo airmon-ng start wlan0

# Check interface mode
iwconfig wlan0

BLE Not Working

# Check Bluetooth status
bluetoothctl
> show

# Enable Bluetooth
sudo systemctl start bluetooth

API Connection Failed

# Start bettercap with API
sudo bettercap -caplet http-ui

# Check API is running
curl http://127.0.0.1:8081/api/session \
  -u user:pass

# Verify environment variables
echo $BETTERCAP_API_URL

Timeout Errors

# Reduce duration
{
  "authorized": true,
  "duration": 30  # Instead of 120
}

# Check network connectivity
ping -c 3 gateway_ip

Architecture

bettercap/
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── README.md                 # This file
└── src/
    ├── index.ts              # Main MCP server
    ├── schemas.ts            # Zod validation schemas
    ├── security.ts           # Security controls and validation
    ├── cli-executor.ts       # CLI and API execution
    └── tools/
        ├── bettercap-net-recon.ts      # Network reconnaissance
        ├── bettercap-wifi-scan.ts      # WiFi scanning
        ├── bettercap-ble-scan.ts       # BLE scanning
        ├── bettercap-http-proxy-log.ts # HTTP log reading
        ├── bettercap-net-sniff.ts      # Packet sniffing
        └── bettercap-session-info.ts   # Session information

Contributing

When adding new tools:

1. Security first: All tools must pass security validation
2. Passive only: No attack or offensive capabilities
3. Validate inputs: Use Zod schemas with descriptions
4. Duration limits: Enforce maximum operation time
5. Error handling: Provide clear error messages
6. Documentation: Update README with examples

License

MIT License - Use responsibly and ethically

Resources

• Bettercap Official Site
• Bettercap Documentation
• Bettercap GitHub
• BPF Filter Syntax
• Network Scanning Laws

Warning

IMPORTANT: This tool provides powerful network reconnaissance capabilities. Misuse can:

• Violate laws and regulations
• Breach corporate security policies
• Cause network disruptions
• Lead to legal consequences

ONLY USE with proper authorization and for legitimate security purposes.