bhyve-mcp

An MCP server for Orbit B-Hyve smart irrigation systems. Query device status, zones, and watering history — or start/stop watering, set rain delays, and manage programs — from Claude Code, Cursor, or any MCP-compatible client.

Why This Exists

I built this to control my sprinkler system from the same AI tools I use for everything else. Instead of opening the B-Hyve app to check zone status or adjust a rain delay, I can do it from a Claude conversation or a Cursor terminal.

It's also a good example of an MCP server that bridges REST (reads) and WebSocket (writes) APIs under a single interface — a different integration pattern than my other MCP servers which are pure REST or REST+SOAP.

Related MCP server: cursor-mcp-server

Features

• Read tools: list devices, device status, zones, programs, watering history

• Write tools: start/stop watering, rain delay, device mode, program updates, smart watering toggle

• Resources: bhyve://devices and bhyve://device/{device_id}/zones

• Transport: stdio (local MCP)

Requirements

• Python 3.10+

• uv (recommended) or pip

• Orbit B-Hyve account

Setup

1. Clone this repo and install dependencies:

cd bhyve-mcp
uv sync

2. Copy credentials:

cp .env.example .env
# Edit .env with your BHYVE_EMAIL and BHYVE_PASSWORD

Cursor / Claude Code configuration

Add to ~/.cursor/mcp.json or your project's .mcp.json:

{
  "mcpServers": {
    "bhyve": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/bhyve-mcp",
        "python",
        "-m",
        "bhyve_mcp.server"
      ],
      "env": {
        "BHYVE_EMAIL": "your-email@example.com",
        "BHYVE_PASSWORD": "your-password"
      }
    }
  }
}

Replace /path/to/bhyve-mcp with the absolute path to this directory.

Development

# Run tests
uv run pytest

# Interactive MCP testing
uv run mcp dev src/bhyve_mcp/server.py

Architecture

• FastMCP (mcp Python SDK) — MCP tool/resource server over stdio

• Vendored pybhyve — B-Hyve REST + WebSocket client (from sebr/bhyve-home-assistant)

• Session wrapper — lazy auth, token refresh on 401/403, structured errors

Write operations (start watering, rain delay, etc.) use the B-Hyve WebSocket API. Read operations use REST polling.

Safety

• start_watering defaults to a 30-minute max unless allow_extended_runtime=true

• Rain delay capped at 168 hours (7 days)

• Watering duration capped at 120 minutes

License

MIT