# kismetwireless-mcp

[Kismet Wireless](https://www.kismetwireless.net/) MCP server — status, datasources, devices, and alerts for AI agents.

Modeled after [wireshark-mcp](../wireshark-mcp): FastMCP stdio, fail-closed preflight, modular tools/prompts/resources, no simulated data.

**Version 1.0.0** — GET-only (readonly REST). No datasource start/stop.

## Quick start

### 1. Docker lab (API without RF adapter)

```powershell
cd kismetwireless-mcp\docker
docker compose up -d
```

- UI: http://127.0.0.1:2501/
- Lab login: `kismet` / `kismet`

### 2. Install MCP package

```powershell
cd kismetwireless-mcp
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install -e .
```

### 3. Doctor + setup

```powershell
$env:KISMET_URL = "http://127.0.0.1:2501"
$env:KISMET_USER = "kismet"
$env:KISMET_PASSWORD = "kismet"
python -m kismet_mcp doctor
python -m kismet_mcp setup
```

### 4. Run (hosts spawn this)

```text
python -m kismet_mcp
```

## Cookbook workflows (preferred)

| Tool | Purpose |
|------|---------|
| `list_workflows` | Catalog of predefined recipes |
| `workflow_capture_health` | Datasources / GPS / sensor readiness |
| `workflow_rf_landscape` | APs + Wi-Fi + BT/BTLE survey |
| `workflow_wids_triage` | Attack-class alerts vs SYSTEM noise |
| `workflow_rogue_ap_hunt` | Duplicate SSIDs / evil-twin signals |
| `workflow_device_hunt` | MAC / SSID / name search |

Suggested order: health → landscape → WIDS triage → rogue hunt.

## Atomic tools

| Tool | Purpose |
|------|---------|
| `check_environment` | Reachability / auth report |
| `kismet_user_status` | Unauthenticated process status |
| `kismet_system_status` | Version, device count, memory |
| `kismet_timestamp` | Server timestamp |
| `list_datasources` | Capture sources |
| `list_recent_devices` | Devices in last N seconds |
| `get_device` | One device by key |
| `list_alerts` | Alert backlog |
| `list_alert_definitions` | Alert type catalog |

## Layout

```text
kismetwireless-mcp/
  docker/                 # compose lab
  docs/                   # Setup, Clients, Security
  examples/               # mcpServers snippet
  src/kismet_mcp/
    __main__.py           # run | setup | doctor
    server.py             # FastMCP
    client.py             # GET-only httpx
    config.py / security.py / preflight.py
    tools/                # environment, system, datasources, devices, alerts
    prompts.py / resources.py
  tests/
```

## Docs

- [Setup](docs/Setup.md)
- [Clients](docs/Clients.md)
- [Security](docs/Security.md)

## Phase 1 Docker smoke (local)

| Endpoint | Result |
|---|---|
| `GET /system/user_status.json` | 200 |
| `GET /system/status.json` (`kismet:kismet`) | 200 |
| datasources / devices | 200 `[]` without RF (expected) |
| alerts | 200 |

## License

MIT