madorn/bond-mcp-server

Bond MCP Server

A Model Context Protocol (MCP) server that provides tools for controlling Bond Bridge smart home devices. This server enables AI assistants like Claude to interact with ceiling fans, fireplaces, shades, lights, and other RF-controlled devices through Bond Bridge hubs.

Features

• Device Management: List and get information about all connected Bond devices
• Fan Control: Control ceiling fan speed, direction, and power state
• Shade Control: Open, close, and set positions for motorized shades
• Light Control: Control dimmable lights and brightness levels
• Custom Actions: Send any Bond API action to devices
• Bridge Information: Get Bond Bridge status and configuration

Quick Start

Prerequisites

• Bond Bridge on your local network
• Bond API token (obtained from Bond Home app)

Getting Your Bond Token

1. Open the Bond Home app on your mobile device
2. Go to Settings → Bond Bridge → Advanced → API
3. Copy the Local Token (not the Cloud Token)

Add to your MCP settings:

{
  "mcpServers": {
    "bond": {
      "command": "podman",
      "args": [
        "run", "-i", "--rm",
        "-e", "BOND_TOKEN=your_token_here",
        "-e", "BOND_HOST=192.168.1.100",
        "quay.io/madorn/bond-mcp-server:latest"
      ]
    }
  }
}

Installation

1. Create and activate virtual environment:

   python3 -m venv bond-mcp-env
   source bond-mcp-env/bin/activate  # On Windows: bond-mcp-env\Scripts\activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment:

   cp .env.example .env
   # Edit .env with your Bond Bridge settings
   

4. Run the server:

   python -m bond_mcp.server
   

Configuration

Create a .env file with your Bond Bridge configuration:

# Required: Bond Bridge settings
BOND_TOKEN=your_bond_api_token_here
BOND_HOST=192.168.1.100

# Optional: Connection settings
BOND_TIMEOUT=10.0
BOND_MAX_RETRIES=3
BOND_RETRY_DELAY=1.0

# Optional: Logging
LOG_LEVEL=INFO

Available Tools

Device Management

• list_devices() - List all Bond devices
• get_device_info(device_id) - Get detailed device information
• get_device_state(device_id) - Get current device state
• get_bridge_info() - Get Bond Bridge information

Device Control

• toggle_device_power(device_id) - Toggle device on/off
• send_custom_action(device_id, action, argument?) - Send custom Bond action

Fan Control

• set_fan_speed(device_id, speed) - Set fan speed (0-8)
• set_fan_direction(device_id, direction) - Set direction ("forward"/"reverse")

Shade Control

• control_shades(device_id, action, position?) - Control shades
  • Actions: "open", "close", "set_position"
  • Position: 0-100 (for set_position action)

Light Control

• set_light_brightness(device_id, brightness) - Set brightness (0-100)

Bond API Reference

This server uses the Bond Local API v2:

• Base URL: http://{bridge_ip}/v2/
• Authentication: Bearer token in Authorization header
• Docs: Bond Local API Documentation

Troubleshooting

Common Issues

1. Connection refused: Ensure Bond Bridge IP is correct and accessible
2. Authentication failed: Verify Bond token is correct (use Local Token, not Cloud Token)
3. Device not found: Check device ID exists using list_devices()
4. Action not supported: Verify device supports the action using get_device_info()

Debug Logging

Enable debug logging by setting LOG_LEVEL=DEBUG in your environment.

License

This project is licensed under the MIT License. See the LICENSE file for details.