HotspotSniffer MCP

Service-level iPhone app traffic capture on Windows, exposed as an MCP server and a CLI.

HotspotSniffer turns a Windows laptop into a controlled Wi-Fi hotspot for an iPhone, combines passive packet capture with an HTTPS interception proxy, and stores one record per app service or submenu in SQLite. An MCP client can drive the workflow: confirm the app, start a service record, wait for the user to finish the operation, stop the record, generate a focused report and read the result.

Authorized use only. Use this only with devices and accounts you own or are explicitly authorized to inspect. The hotspot is a real network and the local CA can impersonate HTTPS sites for devices that trust it. Read SECURITY.md before installing the CA.

中文快速开始 · MCP server guide · Security

Why two capture channels

The passive channel answers "which real domains/IPs does this app contact?" even when the app rejects the proxy certificate. The active channel adds complete request paths when the app accepts the CA. Both channels write into data/hsniff.db.

Related MCP server: Windows Developer Agent MCP

Features

• Windows Mobile Hotspot + iPhone system HTTP proxy, no jailbreak.

• One SQLite record per app service/submenu, with app_name, parent_service, service_name, run_no, focus_domains.

• focus_domains isolates target domains from phone background traffic in reports and MCP responses.

• Markdown report per record plus a JSON summary (session_summaries).

• MCP tools, resources and prompts for agent-driven capture and review.

• The CLI and the MCP server share the same storage and analysis code.

• Request bodies, cookies, passwords and photo content are not stored.

Architecture

iPhone ──Wi-Fi──> Windows Mobile Hotspot (192.168.137.1)
                     │
                     ├─ dumpcap on the Wi-Fi Direct adapter ──> tshark ──> SQLite
                     │       DNS / SNI / QUIC / CONNECT
                     │
                     └─ mitmproxy :8080 ──> SQLite (full URLs)
                             │
                             └─ CA page :8081 ──> iPhone installs/trusts CA

Agent / MCP client ──stdio──> hotspot_sniffer_mcp.server
                                 │
                                 └─ hsniff_lib ──> SQLite + reports + CLI

Requirements

• Windows 11 (the hotspot, Npcap and PowerShell orchestration are Windows-only).

• A Wi-Fi adapter that supports Windows Mobile Hotspot (most Intel/Qualcomm laptop cards).

• Wireshark 4.x with Npcap. The free Npcap installer requires its GUI wizard; silent install is an Npcap OEM feature.

• Python 3.12+.

• iPhone with the HotspotSniffer CA installed and fully trusted.

• Administrator approval once for starting the hotspot and adding the firewall rule.

Install from source

git clone https://github.com/haohaoo3o/HotspotSniffer.git
cd HotspotSniffer
py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
copy config.example.json config.json
notepad config.json      # set a strong hotspot passphrase
python hsniff.py init

pip install -e . installs the MCP SDK (mcp[cli]) and mitmproxy. Wireshark and Npcap are external Windows applications and must be installed separately.

Replace the sample passphrase. Do not commit config.json, data/, captures/, reports/, proxy_cert/ or date-prefixed capture reports.

One-time host setup

python hsniff.py up

• Requests UAC once for the hotspot/firewall and starts dumpcap.

• Starts mitmproxy on 0.0.0.0:8080 and the CA download page on 0.0.0.0:8081.

• Prints the hotspot SSID and proxy/cert URLs.

• The hotspot passphrase is read from config.json.

If you only need to restart the capture after a reboot, python hsniff.py up again (one UAC). python hsniff.py down stops capture/proxy/hotspot.

iPhone setup

1. Connect to the hotspot SSID from config.json.

2. Wi-Fi → current network → Configure Proxy → Manual:

   • Server 192.168.137.1

   • Port 8080

   • Authentication off

3. Safari → http://192.168.137.1:8081/ → install the profile.

4. Settings → General → VPN & Device Management → install HotspotSniffer CA.

5. Settings → General → About → Certificate Trust Settings → enable full trust.

6. For cleaner measurements, turn off Limit IP Address Tracking and iCloud Private Relay for this network.

Verify with python hsniff.py status: hotspot On, capture running, proxy and cert page listening. A test HTTPS site should now produce http_request events.

CLI workflow

# 1. Remember the app
python hsniff.py app set --name "MyApp"

# 2. Start one service / submenu
python hsniff.py service start --parent "Dashboard" --name "Orders" --focus "example.edu.cn"

# 3. Operate the service on the iPhone and wait until it finishes

# 4. Stop, parse, report, summarize (waits 10–20s for pcap rotation)
python hsniff.py service stop

# 5. Review
python hsniff.py service list
python hsniff.py analyze --session last
python hsniff.py export --session last --out reports\orders.csv

• --parent creates a Parent > Submenu hierarchy.

• --focus is a comma-separated list of domain suffixes; the report gets a "Target domains" section that excludes phone background traffic.

• Repeating the same app/service increments run_no (1st, 2nd, …).

• A record is stored in SQLite even if the report generation is interrupted; call python hsniff.py analyze --session <id> to regenerate.

MCP server

The MCP server uses the official Python SDK v2 (MCPServer) over stdio.

# Development / inspector
.venv\Scripts\mcp.exe dev hotspot_sniffer_mcp/server.py

# Or run stdio directly
.venv\Scripts\python.exe -m hotspot_sniffer_mcp.server

Client configuration (Claude Desktop, Cursor, Qoder or any MCP client):

{
  "mcpServers": {
    "hotspot-sniffer": {
      "command": "C:\\path\\to\\HotspotSniffer\\.venv\\Scripts\\python.exe",
      "args": ["-m", "hotspot_sniffer_mcp.server"],
      "env": {
        "HSNIFF_ROOT": "C:\\path\\to\\HotspotSniffer"
      }
    }
  }
}

HSNIFF_ROOT tells the server where schema.sql, scripts/ and config.json live when it is not started from the checkout. The MCP server does not start the hotspot; start the host environment once with hsniff up.

MCP tools

Resources: hsniff://status, hsniff://services, hsniff://service/{id}/summary, hsniff://service/{id}/report, hsniff://schema.

Prompts: capture_service_workflow, analyze_capture.

Agent skill

skills/hotspot-sniffer/SKILL.md packages the same workflow for MCP-capable agents. Copy the folder into your agent's skills directory; it uses the hotspot-sniffer MCP server and does not require any extra code.

See docs/MCP.md for the full client setup, agent workflow and safety notes.

Data model

Example:

SELECT session_id, app_name, parent_service, service_name, run_no,
       duration_s, hosts_count, endpoints_count, mitm_http, report_path
FROM v_service_runs ORDER BY started_at DESC;

Security and privacy

• Authorized devices/accounts only. Installing a CA on someone else's phone is not acceptable without explicit consent.

• The CA private key (proxy_cert/.mitm/mitmproxy-ca.pem) can impersonate any site to a trusting device. Never commit or share it.

• Request bodies, cookies, passwords, tokens and photo bytes are not stored. MCP get_events strips URL query strings.

• Reports and SQLite still contain hostnames and internal paths. Clean runtime data before sharing a checkout.

• Use a strong hotspot passphrase and stop the hotspot after capture.

• Use GitHub Security Advisories for vulnerability reports.

Limitations

• IPv4 only: Windows ICS does not provide IPv6 to hotspot clients by default.

• Pinned Apple/system services reject the user CA; passive SNI/IP is still recorded, but HTTPS content is not decrypted.

• HTTP/3/QUIC is not proxied by mitmproxy; passive Initial/SNI only.

• A page opening is not the same as an action submission. A "page shell" record may not contain the final submit API (e.g., loss report, password change, photo upload); the report labels what was actually observed.

• Phone background traffic (health, wearable, push, OS services) can appear in a record. Use focus to isolate the target and read the full report for evidence.

• The free Npcap installer is interactive; automation cannot fully silently install the driver.

Development

ruff check .
pytest -q

Python tests cover the SQLite session/summary layer and do not need Wireshark, Npcap or an iPhone. Live integration testing is manual on Windows; include what you tested in the pull request. See CONTRIBUTING.md.

License

MIT. See LICENSE.