pyBTMCP - BLE Device Simulator with MCP Integration

A comprehensive BLE (Bluetooth Low Energy) fitness device simulator that enables AI agents like Claude to control simulated heart rate monitors, treadmills, and cycling trainers via the Model Context Protocol (MCP).

Overview

pyBTMCP consists of three integrated components:

1. ESP32 Firmware - Runs on ESP32 microcontrollers to simulate BLE fitness devices
2. Python Backend - FastAPI server with MQTT broker for device communication
3. MCP Server - Enables Claude and other AI agents to control devices

┌─────────────────┐     ┌──────────────────────────────────────────┐
│  Claude/AI      │     │           Docker Container               │
│  (MCP Client)   │◄───►│  ┌─────────┐  ┌───────┐  ┌──────────┐   │
└─────────────────┘     │  │   MCP   │  │ MQTT  │  │ FastAPI  │   │
                        │  │ Server  │◄►│Broker │◄►│  + Web   │   │
                        │  └─────────┘  └───┬───┘  └──────────┘   │
                        └──────────────────│───────────────────────┘
                                           │
                        ┌──────────────────▼───────────────────────┐
                        │              ESP32 Devices               │
                        │  ┌─────────┐ ┌─────────┐ ┌─────────┐    │
                        │  │   HR    │ │Treadmill│ │  Bike   │    │
                        │  │ Monitor │ │         │ │ Trainer │    │
                        │  └─────────┘ └─────────┘ └─────────┘    │
                        └──────────────────────────────────────────┘

Quick Start

Prerequisites

• Docker
• (Optional) ESP32 development board for hardware simulation

1. Build the Docker Image

docker build -t pybtmcp:latest .

2. Run the Container

docker run -it --rm \
  -p 1883:1883 \
  -p 8000:8000 \
  --name pybtmcp \
  pybtmcp:latest

This starts:

• MQTT Broker on port 1883 (for ESP32 device connections)
• Web UI / API on port 8000 (browser interface)
• MCP Server on stdio (for Claude integration)

3. Access the Web UI

Open http://localhost:8000 in your browser to see connected devices and control them manually.

MCP Integration (Claude Desktop)

To use pyBTMCP with Claude Desktop, add it to your MCP configuration:

Configuration File Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Server Configuration

{
  "mcpServers": {
    "ble-simulator": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "1883:1883",
        "-p", "8000:8000",
        "--name", "pybtmcp",
        "pybtmcp:latest"
      ]
    }
  }
}

Restart Claude Desktop

After saving the configuration, restart Claude Desktop. You should see the "ble-simulator" MCP server available.

MCP Integration (Claude Code CLI)

To add pyBTMCP to Claude Code, run:

claude mcp add ble-simulator \
  -s user \
  -- docker run -i --rm -p 1883:1883 -p 8000:8000 --name pybtmcp pybtmcp:latest

This adds the MCP server to your user configuration. Use -s project instead to add it to the current project only.

To verify the server was added:

claude mcp list

MCP Tools Reference

Once configured, Claude can use these tools to control BLE devices:

list_devices

List all connected ESP32 BLE simulator devices.

No parameters required

configure_device

Configure an ESP32 to simulate a specific BLE device type.

set_heart_rate

Set the simulated heart rate for a heart rate monitor device.

set_treadmill_values

Set simulated values for a treadmill device.

set_bike_values

Set simulated values for a bike/cycling trainer device.

get_device_status

Get the current status and values of a specific device.

Web UI Features

The web interface at http://localhost:8000 provides:

• Real-time device status via WebSocket (live updates)
• Device type configuration (Heart Rate, Treadmill, Bike)
• Preset values for quick testing (Rest, Warm Up, Cardio, etc.)
• Manual sliders for fine-grained control
• Unit switching (Metric/Imperial)
• HR variation toggle for realistic heart rate simulation

Connection Status Indicator

The UI shows WebSocket connection status:

• 🟢 Live - Connected and receiving real-time updates
• 🟡 Connecting... - Attempting to connect
• 🔴 Disconnected - Using polling fallback

REST API

The FastAPI backend provides these endpoints:

API documentation is available at http://localhost:8000/docs (Swagger UI).

ESP32 Firmware Setup

Hardware Requirements

• ESP32 development board (ESP32-DevKitC, ESP32-WROOM, etc.)
• USB cable for programming

Building the Firmware

1. Install PlatformIO
2. Navigate to the firmware directory:

   cd firmware/esp32_ble_sim
   

3. Build and upload:

   pio run -t upload
   

Initial Configuration

1. On first boot, the ESP32 creates a WiFi access point: BLE-Sim-XXXX
2. Connect to the AP and open http://192.168.4.1
3. Enter your WiFi credentials and MQTT broker address
4. The device will restart and connect to your network

MQTT Topics

The ESP32 devices communicate via MQTT:

Development

Running Locally (without Docker)

1. Install dependencies:

   pip install -r requirements.txt
   

2. Start an MQTT broker (e.g., Mosquitto):

   mosquitto -c config/mosquitto.conf
   

3. Start the API server:

   uvicorn src.api.main:app --reload --port 8000
   

4. Run the MCP server (for testing):

   python -m src.mcp.server
   

Environment Variables

Project Structure

pyBTMCP/
├── src/
│   ├── mcp/
│   │   └── server.py          # MCP server implementation
│   ├── api/
│   │   ├── main.py            # FastAPI app + WebSocket
│   │   ├── routes.py          # REST API routes
│   │   ├── mqtt_client.py     # MQTT connection manager
│   │   └── device_registry.py # Device state tracking
│   └── web/
│       └── static/
│           └── index.html     # Web UI
├── firmware/
│   └── esp32_ble_sim/         # PlatformIO ESP32 project
├── config/
│   └── mosquitto.conf         # MQTT broker config
├── Dockerfile
├── entrypoint.sh
├── requirements.txt
└── mcp-config.example.json    # Example Claude Desktop config

Supported BLE Services

Troubleshooting

MCP server not appearing in Claude Desktop

1. Ensure Docker is running
2. Check the config file path is correct for your OS
3. Restart Claude Desktop after saving config
4. Check Docker logs: docker logs pybtmcp

ESP32 not connecting

1. Verify WiFi credentials are correct
2. Ensure MQTT broker is reachable from ESP32's network
3. Check MQTT broker is listening on port 1883
4. Use mosquitto_sub -t "ble-sim/#" -v to monitor MQTT traffic

Web UI not updating

1. Check browser console for WebSocket errors
2. Verify the container is running: docker ps
3. The UI falls back to 5-second polling if WebSocket disconnects

License

MIT License