microbit-mcp
An MCP (Model Context Protocol) server for the micro:bit that enables LLMs to interact with micro:bit devices.
Features
Tools
- display_message: Display text messages on the micro:bit LED matrix
- display_image: Display custom images on the micro:bit LED matrix using a 5x5 grid format
- wait_for_button_press: Wait for a button press on the micro:bit with optional button selection and timeout
- get_temperature: Return the real-time reading from the micro:bit's built-in temperature sensor
Setup
- Flash the
src/microbit/main.pyprogram to your micro:bit - Connect the micro:bit via USB
- Run the MCP server:
uv run microbit-mcp - Configure your MCP client to connect to this server
Command Line Options
The MCP server supports several command-line options for configuration:
# Use default port (recommended for most users)
uv run microbit-mcp
# Specify a custom serial port
uv run microbit-mcp --port /dev/tty.usbmodem1234
uv run microbit-mcp -p COM3 # Windows example
# List available serial ports to find your micro:bit
uv run microbit-mcp --list-ports
# Show help and usage information
uv run microbit-mcp --help
Finding Your micro:bit Port
If you're unsure which port your micro:bit is using, run:
uv run microbit-mcp --list-ports
This will show all available serial ports and highlight likely micro:bit devices. The output will look something like:
Available Serial Ports:
Likely micro:bit devices:
/dev/cu.usbmodem2114202 - "BBC micro:bit CMSIS-DAP"
Hardware ID: USB VID:PID=0D28:0204
All serial ports (3 found):
/dev/cu.usbmodem2114202 - "BBC micro:bit CMSIS-DAP" ⭐
/dev/cu.Bluetooth-Incoming-Port - Bluetooth-Incoming-Port
/dev/cu.usbserial-A1B2C3D4 - USB Serial Device
Recommended: Use /dev/cu.usbmodem2114202 for your micro:bit
The ⭐ symbol indicates ports that are likely micro:bit devices.
Button Press Tool
The wait_for_button_press tool allows you to wait for button presses on the micro:bit with flexible configuration options.
Parameters (all optional)
- button (optional): Which specific button to wait for
"a"- Wait only for button A"b"- Wait only for button B- If not specified, waits for any button press
- timeout (optional): Maximum time to wait in seconds (default: 10.0)
Usage Examples
Wait for any button with default timeout:
{}
Wait for any button with custom timeout:
{
"timeout": 5.0
}
Wait for specific button A:
{
"button": "a"
}
Wait for button B with custom timeout:
{
"button": "b",
"timeout": 3.0
}
Response Format
Success response:
{
"button_pressed": "a",
"timeout": false,
"timestamp": 12345,
"waited_for": "any"
}
Timeout response:
{
"button_pressed": null,
"timeout": true,
"timestamp": null,
"waited_for": "any",
"timeout_duration": 10.0
}
Communication Protocol
The server communicates with the micro:bit using simple text commands over serial:
MESSAGE:<text>- Display text messageIMAGE:<pattern>- Display image pattern (e.g., "00300:03630:36963:03630:00300")TEMP:- Request temperature readingWAIT_BUTTON:<button>:<timeout>- Wait for button press (e.g., "WAIT_BUTTON🅰️10" or "WAIT_BUTTON:any:5")
The micro:bit responds with status events and data in the format:
STATUS|<message>|<timestamp>- General status updatesTEMP|<celsius>|<timestamp>- Temperature responseBUTTON|<button>|<action>|<timestamp>- Button press event (e.g., "BUTTON|a|pressed|12345")BUTTON_TIMEOUT|<waited_for>|<timeout_duration>- Button wait timeout
Using the MCP Inspector
To test/debug the server, you can also use the MCP Inspector. To launch the inspector:
- Run
npx @modelcontextprotocol/inspector(recommend LTS-version of Node) - The inspector will launch in a new browser window.
- Set transport type to STDIO, command is the full path to your uv binary (e.g.,
/Users/yourname/.local/bin/uv), arguments is--directory /full-path-to-the-mcp-server run microbit-mcp - Click on the Connect button to connect and inspect the MCP server.
Project Structure
The project is organized as follows:
microbit-mcp/
├── src/
│ ├── mcp_server/ # Main MCP server package
│ │ ├── server.py # Main server entry point
│ │ ├── microbit_client.py # Serial communication with micro:bit
│ │ ├── protocol.py # Command/response protocol definitions
│ │ └── tools/ # MCP tools organized by category
│ │ ├── display.py # Display-related tools
│ │ ├── sensors.py # Sensor-related tools
│ │ └── input.py # Input-related tools
│ ├── microbit/ # Micro:bit firmware
│ │ ├── main.py # Firmware to flash to micro:bit
│ │ └── README.md # Micro:bit setup instructions
│ └── examples/ # Usage examples
└── README.md # This file
Metadata
Release files for iflow-mcp_simonguest-microbit-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_simonguest_microbit_mcp-0.1.0.tar.gz | 64.8 kB | Without provenance | Details for iflow_mcp_simonguest_microbit_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_simonguest_microbit_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_simonguest_microbit_mcp-0.1.0-py3-none-any.whl |
Total release size: 78.8 kB
Release files / iflow_mcp_simonguest_microbit_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_simonguest_microbit_mcp-0.1.0.tar.gz |
|---|---|
| Size | 64.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0eabc370d32a9cb1f09d621581b400218ab89f0c632db6d64fd3e97763ef2218
|
|
BLAKE2b-256 checksum How to use checksums |
babaa92676ae1a3343ec999fdc956816c76d4e12fb9adbf26311dc0613476324
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_simonguest_microbit_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_simonguest_microbit_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3d3425b459d5bf8f22a635d723cd520d532f8ad440d95c0d678be489d205df00
|
|
BLAKE2b-256 checksum How to use checksums |
ce02fa13f3ea7142e4a8bf57ca509acde7b2a3d58213e671f7c0fa3c767cd8cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_simonguest-microbit-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.