Bond MCP Server

🚀 Bond MCP Server

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

✨ Features

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

🚀 Quick Start

Prerequisites

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

Getting Your Bond Token

1. Open the Bond Home app on your mobile device.
2. Navigate 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

💻 Usage Examples

Basic Usage

Here are some basic usage examples of the available tools:

Device Management

# List all Bond devices
list_devices()

# Get detailed device information
get_device_info(device_id)

# Get current device state
get_device_state(device_id)

# Get Bond Bridge information
get_bridge_info()

Device Control

# Toggle device on/off
toggle_device_power(device_id)

# Send custom Bond action
send_custom_action(device_id, action, argument?)

Fan Control

# Set fan speed (0 - 8)
set_fan_speed(device_id, speed)

# Set direction ("forward"/"reverse")
set_fan_direction(device_id, direction)

Shade Control

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

Light Control

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

Advanced Usage

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

📚 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.