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:

ESP32 Firmware - Runs on ESP32 microcontrollers to simulate BLE fitness devices
Python Backend - FastAPI server with MQTT broker for device communication
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

Install PlatformIO
Navigate to the firmware directory:
```
cd firmware/esp32_ble_sim
```
Build and upload:
```
pio run -t upload
```

Initial Configuration

On first boot, the ESP32 creates a WiFi access point: BLE-Sim-XXXX
Connect to the AP and open http://192.168.4.1
Enter your WiFi credentials and MQTT broker address
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)

Install dependencies:
```
pip install -r requirements.txt
```
Start an MQTT broker (e.g., Mosquitto):
```
mosquitto -c config/mosquitto.conf
```

Start the API server:

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

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

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

ESP32 not connecting

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

Web UI not updating

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

License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
config		config
firmware/esp32_ble_sim		firmware/esp32_ble_sim
src		src
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
entrypoint.sh		entrypoint.sh
mcp-config.example.json		mcp-config.example.json
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

pyBTMCP - BLE Device Simulator with MCP Integration

Overview

Quick Start

Prerequisites

1. Build the Docker Image

2. Run the Container

3. Access the Web UI

MCP Integration (Claude Desktop)

Configuration File Location

Add the Server Configuration

Restart Claude Desktop

MCP Integration (Claude Code CLI)

MCP Tools Reference

list_devices

configure_device

set_heart_rate

set_treadmill_values

set_bike_values

get_device_status

Web UI Features

Connection Status Indicator

REST API

ESP32 Firmware Setup

Hardware Requirements

Building the Firmware

Initial Configuration

MQTT Topics

Development

Running Locally (without Docker)

Environment Variables

Project Structure

Supported BLE Services

Troubleshooting

MCP server not appearing in Claude Desktop

ESP32 not connecting

Web UI not updating

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`list_devices`

`configure_device`

`set_heart_rate`

`set_treadmill_values`

`set_bike_values`

`get_device_status`

Packages