# mcbirdcage

[MCP](https://modelcontextprotocol.io/) server for controlling Winegard satellite dishes through conversational tools. Built on [FastMCP](https://gofastmcp.com/), exposes 36 tools for dish positioning, signal analysis, firmware inspection, and satellite pass planning.

## Install

```bash
# Add to Claude Code
claude mcp add mcbirdcage -- uvx mcbirdcage

# Or run standalone
uvx mcbirdcage
```

## Demo Mode

No dish required. Set `BIRDCAGE_DEMO=1` to get simulated responses for all tools:

```bash
BIRDCAGE_DEMO=1 uvx mcbirdcage
```

## Tools

36 tools across six groups:

| Group | Count | Examples |
|-------|-------|---------|
| Connection | 3 | `connect`, `disconnect`, `status` |
| Movement | 9 | `get_position`, `move_to`, `home_motor`, `stow` |
| Signal | 8 | `get_rssi`, `enable_lna`, `az_sweep`, `get_lock_status` |
| System | 11 | `nvs_dump`, `get_firmware_id`, `set_pid_gains`, `get_a3981_diag` |
| Satellite | 4 | `search_satellites`, `get_passes`, `get_visible_targets` |
| Console | 1 | `send_raw_command` (direct firmware access) |

Plus 5 resources (hardware specs, NVS reference, firmware docs) and 3 prompts.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `BIRDCAGE_DEMO` | `0` | Enable demo mode (no hardware) |
| `BIRDCAGE_PORT` | `/dev/ttyUSB0` | Serial port path |
| `BIRDCAGE_FIRMWARE` | `hal205` | Firmware variant (`hal000`, `hal205`, `g2`) |
| `BIRDCAGE_CRAFT_URL` | -- | Craft API URL for live satellite TLEs |

## Documentation

Full tool reference and hardware setup: **[birdcage.warehack.ing](https://birdcage.warehack.ing)**

## Credits

- **Gabe Emerson (KL1FI / [saveitforparts](https://github.com/saveitforparts))** -- original Winegard rotor scripts
- **Chris Davidson ([cdavidson0522](https://github.com/cdavidson0522))** -- Carryout G2 sky scan and rotator control

## License

MIT