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.

Parameter	Type	Required	Description
device_id	string	Yes	The ESP32 device ID
device_type	string	Yes	One of: heart_rate, treadmill, bike

set_heart_rate

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

Parameter	Type	Required	Description
device_id	string	Yes	The ESP32 device ID
bpm	integer	Yes	Heart rate (30-220 BPM)

set_treadmill_values

Set simulated values for a treadmill device.

Parameter	Type	Required	Description
device_id	string	Yes	The ESP32 device ID
speed	number	No	Speed in km/h (0-25)
incline	number	No	Incline percentage (-5 to 30)

set_bike_values

Set simulated values for a bike/cycling trainer device.

Parameter	Type	Required	Description
device_id	string	Yes	The ESP32 device ID
power	integer	No	Power in watts (0-2000)
cadence	integer	No	Cadence in RPM (0-200)
speed	number	No	Speed in km/h (0-80)

get_device_status

Get the current status and values of a specific device.

Parameter	Type	Required	Description
device_id	string	Yes	The ESP32 device ID

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:

Method	Endpoint	Description
GET	/api/devices	List all devices
GET	/api/devices/{id}	Get device by ID
POST	/api/devices/{id}/configure	Configure device type
POST	/api/devices/{id}/values	Set device values
GET	/health	Health check
WS	/ws	WebSocket for real-time updates

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:

Topic	Direction	Description
ble-sim/{id}/status	Device → Server	Device online status
ble-sim/{id}/values	Device → Server	Current sensor values
ble-sim/{id}/config	Server → Device	Device type configuration
ble-sim/{id}/set	Server → Device	Set sensor values

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

Variable	Default	Description
MQTT_HOST	localhost	MQTT broker hostname
MQTT_PORT	1883	MQTT broker port

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

Device Type	BLE Service	Characteristics
Heart Rate Monitor	Heart Rate Service (0x180D)	Heart Rate Measurement
Treadmill	Fitness Machine Service (0x1826)	Treadmill Data
Bike Trainer	Cycling Power Service (0x1818)	Cycling Power Measurement

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