HeartMonitor

English ver. | 中文版

Bluetooth Low Energy (BLE) heart rate monitor toolkit with two interfaces:

• A FastAPI-powered REST server that discovers, connects to, and streams heart rate metrics from BLE devices such as smart watches or chest straps.
• An MCP (Model Context Protocol) server exposing the same capabilities for AI copilots.

Prerequisites

• A smartwatch or other devices that supports BLE heart rate broadcasting.
• Python 3.10 or newer
• Windows with Bluetooth Low Energy support (the project also runs on Linux and macOS if BLE is available)
• uv (recommended) or pip for dependency management

Installation

1. Install dependencies:

   uv sync

   If you prefer pip, run pip install -r requirements.txt after generating the lockfile with uv pip compile pyproject.toml -o requirements.txt.

2. Review .env and adjust the options to match your runtime environment. The application will create the file automatically on first launch if it is missing.

   SERVER_HOST=127.0.0.1
   SERVER_PORT=8000
   SERVER_RELOAD=false
   AUTO_RECONNECT=false
   BLE_DEVICE_ADDRESSES=

   • SERVER_HOST / SERVER_PORT control how the API server listens.
   • SERVER_RELOAD toggles Uvicorn's auto-reload; set to true for iterative dev loops.
   • AUTO_RECONNECT automatically connects to the first known device during startup when set to true.
   • BLE_DEVICE_ADDRESSES stores a comma-separated history of devices you have connected to. The application appends to this list automatically.

Running the FastAPI server

uv run main.py

Once running, open http://<SERVER_HOST>:<SERVER_PORT>/docs to explore the interactive Swagger UI.

Key endpoints

Method	Path	Description
GET	/health	Simple liveness probe
GET	/devices/known	List of previously connected BLE addresses
POST	/devices/scan	Scan for nearby BLE devices
POST	/devices/connect	Connect to a device by address (preferred) or name fragment
POST	/devices/disconnect	Stop monitoring and release the connection
GET	/metrics/heart-rate	Fetch the latest heart rate metrics

All responses and logs are in English for easier integration with other tools.

Connecting to a device programmatically

Please make sure you enabled "heart rate broadcasting" function on your smart devices.

Send the device address you obtained from /devices/scan or /devices/known:

POST /devices/connect
{
	"address": "E4:96:52:7F:BA:C3"
}

If an address is not available, you can still provide a name field with a partial device name, and the API will attempt to find the closest match.

When AUTO_RECONNECT is enabled, the server tries to connect automatically to the first address stored in BLE_DEVICE_ADDRESSES during startup.

Running the MCP server

The MCP server exposes high-level tools for AI agents.

uv run mcp_server.py

Available tools:

• scan_ble_devices() – enumerate nearby BLE devices.
• connect_ble_device(device_address: str | None, device_name: str | None) – connect to a device.
• disconnect_ble_device() – release the active connection.
• get_current_heart_rate() – retrieve the most recent heart rate values.

Development tips

• Run python -m compileall . to catch syntax issues quickly.
• Enable uvicorn debug logging with the --log-level debug flag during development.
• The application persists connected BLE addresses back to .env; ensure the file is writable.

Troubleshooting

• BLE permissions – Windows requires the Bluetooth radio to be switched on and accessible to the Python process.
• Multiple connections – If you connect to the already active device, the server reuses the connection instead of reopening it.
• Address persistence – Delete the BLE_DEVICE_ADDRESSES value in .env if you need to reset the history.