# MikroTik WiFi Users

REST API and MCP server for querying connected WiFi devices from MikroTik RouterOS.

Connects to RouterOS via its REST API, enriches device data with DHCP leases and ARP table entries, and exposes everything through a FastAPI REST API and an MCP (Model Context Protocol) SSE endpoint.

## Features

- List connected WiFi devices with signal strength, data rates, and traffic stats
- Enrich device data with hostnames and IPs from DHCP leases and ARP table
- Filter devices by wireless interface
- Default (compact) and detailed response modes
- Paginated device listing - It's easy to get too much devices now
- WiFi interface listing - Great if you have multiple APs and manage them through CAPsMAN
- RouterOS system information - good for fast checks without opening app
- MCP server with SSE transport (compatible with Open WebUI, Claude Code, etc.)
- Separate API key authentication for REST and MCP endpoints

## Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/) package manager
- MikroTik RouterOS device with WiFiWave2 and REST API enabled (port 80/443)

## Setup

```bash
# Clone and install
git clone <repo-url>
cd mikrotik-wifi-users
uv sync

# Configure
cp .env.example .env
# Edit .env with your RouterOS credentials and API keys
```

### Environment variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ROUTEROS_HOST` | RouterOS device IP/hostname | `localhost` |
| `ROUTEROS_PORT` | REST API port | `80` |
| `ROUTEROS_USER` | RouterOS username | `admin` |
| `ROUTEROS_PASSWORD` | RouterOS password | |
| `ROUTEROS_SSL` | Enable HTTPS | `false` |
| `API_KEY` | Bearer token for REST endpoints | |
| `MCP_API_KEY` | Bearer token for MCP endpoints | |
| `LOG_LEVEL` | Logging level | `INFO` |
| `DEBUG` | Enable debug mode | `false` |

## Usage

### Run locally

```bash
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
```

### Run with Docker

```bash
docker compose up -d --build
```

The API listens on `127.0.0.1:8490` by default.

### API endpoints

All endpoints except `/health` require a Bearer token in the `Authorization` header.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | Health check (public) |
| `GET` | `/devices` | List connected devices |
| `GET` | `/devices/{mac}` | Get device by MAC address |
| `GET` | `/interfaces/wifi` | List WiFi interfaces |
| `GET` | `/system/info` | RouterOS system information |
| `GET` | `/docs` | Swagger UI (public) |

#### Query parameters for `/devices`

- `interface` — filter by interface name (e.g. `cap-wifi1`)
- `detailed` — include all fields (`true`/`false`, default `false`)
- `page` — page number (default `1`)
- `page_size` — items per page (default `50`)

### MCP

The MCP server is available at `/mcp/sse` using SSE transport. Authenticate with `MCP_API_KEY` as a Bearer token.

#### Claude Code

Add to your MCP config:

```json
{
  "mcpServers": {
    "mikrotik-wifi": {
      "type": "sse",
      "url": "http://localhost:8490/mcp/sse",
      "headers": {
        "Authorization": "Bearer <your-mcp-api-key>"
      }
    }
  }
}
```

#### Available MCP tools

- `list_devices` — list connected devices (supports `interface` filter and `detailed` flag)
- `get_device` — get device details by MAC address
- `list_wifi_interfaces` — list WiFi interfaces
- `get_system_info` — get RouterOS system information
- `health_check` — check API and RouterOS connectivity

## Security

> **Warning:** By default, the connection to RouterOS uses plain HTTP (`ROUTEROS_SSL=false`). This transmits credentials and data in cleartext over the network. In production or untrusted networks, enable HTTPS by setting `ROUTEROS_SSL=true` and configuring a valid TLS certificate on your RouterOS device. See the [MikroTik TLS documentation](https://help.mikrotik.com/docs/spaces/ROS/pages/2031655/Certificates) for setup instructions.

## License

[MIT](LICENSE)