technic-hub-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ .pytest_cache/
4
+ .ruff_cache/
5
+ build/
6
+ dist/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Gustavo Pabon
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,271 @@
1
+ Metadata-Version: 2.5
2
+ Name: technic-hub-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server that lets AI assistants read and control a LEGO Technic Hub and its motors over Bluetooth.
5
+ Project-URL: Homepage, https://github.com/gustavo-pabon/mhs-pilot/tree/main/technic-hub-mcp
6
+ Project-URL: Source, https://github.com/gustavo-pabon/mhs-pilot
7
+ Project-URL: Issues, https://github.com/gustavo-pabon/mhs-pilot/issues
8
+ Author: Gustavo Pabon
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: ble,bluetooth,lego,lwp3,mcp,model-context-protocol,motor,powered-up,technic
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: MacOS
15
+ Classifier: Operating System :: Microsoft :: Windows
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: System :: Hardware
24
+ Requires-Python: >=3.10
25
+ Requires-Dist: bleak>=3.0
26
+ Requires-Dist: mcp>=2.3
27
+ Description-Content-Type: text/markdown
28
+
29
+ # LEGO Technic Hub MCP server
30
+
31
+ An [MCP](https://modelcontextprotocol.io) server that lets AI assistants read and control a LEGO Technic Hub (88012)
32
+ over Bluetooth LE: the motors and sensors on its four ports, its built-in sensors and its light. It implements LEGO's
33
+ [Wireless Protocol 3.0](https://lego.github.io/lego-ble-wireless-protocol-docs/) (LWP3), with tools for the hub's
34
+ properties, alerts and actions, the devices on its ports and their modes, and the port output commands.
35
+
36
+ ## Requirements
37
+
38
+ - Python 3.10 or later.
39
+ - A computer with Bluetooth LE: macOS, Linux (BlueZ) or Windows 10 or later, through
40
+ [bleak](https://github.com/hbldh/bleak).
41
+ - The hub with LEGO's own firmware. Pybricks firmware replaces LWP3, so this server can't talk to a hub that runs it.
42
+ - The hub switched on and not connected to another app or device: it accepts one connection at a time. Press its
43
+ button: the light flashes white while the hub waits for a connection and turns solid blue once connected. A hub that
44
+ nothing connects to switches itself off after a short while.
45
+
46
+ On macOS, the app that starts the server (VS Code, Claude, Terminal…) needs Bluetooth access: **System Settings →
47
+ Privacy & Security → Bluetooth**.
48
+
49
+ ## Installation
50
+
51
+ Install it from [PyPI](https://pypi.org/project/technic-hub-mcp/) into a virtual environment:
52
+
53
+ ```bash
54
+ python3 -m venv .venv
55
+ .venv/bin/pip install technic-hub-mcp
56
+ ```
57
+
58
+ This installs the `technic-hub-mcp` command in `.venv/bin/`. It runs the server over stdio. With
59
+ [uv](https://docs.astral.sh/uv/), `uvx technic-hub-mcp` runs it without installing it first.
60
+
61
+ ## Configuration
62
+
63
+ Add the command to your MCP client, using its absolute path. With uv, use `"command": "uvx"` and
64
+ `"args": ["technic-hub-mcp"]` instead.
65
+
66
+ VS Code (`.vscode/mcp.json`):
67
+
68
+ ```json
69
+ {
70
+ "servers": {
71
+ "technic-hub": {
72
+ "type": "stdio",
73
+ "command": "/absolute/path/to/.venv/bin/technic-hub-mcp"
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ Claude Desktop (`claude_desktop_config.json`):
80
+
81
+ ```json
82
+ {
83
+ "mcpServers": {
84
+ "technic-hub": {
85
+ "command": "/absolute/path/to/.venv/bin/technic-hub-mcp"
86
+ }
87
+ }
88
+ }
89
+ ```
90
+
91
+ Options, passed in `args`:
92
+
93
+ | Option | Default | Description |
94
+ | --- | --- | --- |
95
+ | `--address ADDRESS` | First Technic Hub found | Bluetooth address of the hub (a UUID on macOS). Use it when several hubs are nearby. |
96
+ | `--timeout SECONDS` | `10` | How long to search for and connect to the hub. |
97
+
98
+ The server looks for a hub that advertises the LWP3 service as a Technic Hub, and connects on the first tool call. If
99
+ the connection drops, for example because the hub switched itself off, the next tool call reconnects once the hub is
100
+ on again. When the server stops, it brakes the motors and disconnects.
101
+
102
+ To try the server without an AI client, open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
103
+
104
+ ```bash
105
+ npx @modelcontextprotocol/inspector .venv/bin/technic-hub-mcp
106
+ ```
107
+
108
+ ## Tools
109
+
110
+ Tools take ports as a letter, `A` to `D`, a synchronized pair such as `AB` (see `connect_virtual_port`), or a port
111
+ number. The hub's built-in devices only have numbers; on the hub this was tested with, they are 50 (light),
112
+ 59 (current), 60 (voltage), 61 and 96 (temperature), 97 (accelerometer), 98 (gyro), 99 (tilt) and 100 (gesture).
113
+ `list_ports` shows them all.
114
+
115
+ The hub:
116
+
117
+ | Tool | Protocol message | Notes |
118
+ | --- | --- | --- |
119
+ | `get_hub_info` | Hub Properties (`0x01`) | Name, firmware and hardware versions, battery, signal, MAC addresses and the other properties, and what the hub advertised |
120
+ | `get_hub_alerts` | Hub Alerts (`0x03`) | Low voltage, high current, low signal strength and over-power condition |
121
+ | `set_hub_name(name)` | Hub Properties: Set | 1–14 printable ASCII characters. The hub keeps the name and advertises it |
122
+ | `reset_hub_name` | Hub Properties: Reset | Restores the default name |
123
+ | `set_busy_indication(enabled)` | Hub Actions `0x05`, `0x06` | Shows or clears the busy indication on the light |
124
+ | `set_port_vcc(enabled)` | Hub Actions `0x03`, `0x04` | Switches the supply voltage of the ports |
125
+ | `disconnect_hub` | Hub Actions `0x02` | The next tool call reconnects while the hub is still on |
126
+ | `switch_off_hub` | Hub Actions `0x01` | Destructive: the hub must then be switched on by hand |
127
+
128
+ Ports and sensors:
129
+
130
+ | Tool | Protocol messages | Returns |
131
+ | --- | --- | --- |
132
+ | `list_ports` | Hub Attached I/O (`0x04`) | Every port with a device: connector, built-in or virtual pair, device type and revisions |
133
+ | `get_port_info(port)` | Port Information (`0x21`, `0x43`), Port Mode Information (`0x22`, `0x44`) | The device's capabilities and, per mode: name, raw, percent and SI ranges, unit, mappings and value format |
134
+ | `read_port_value(port, mode)` | Port Input Format Setup (`0x41`), Port Value (`0x21`, `0x45`) | The values of one mode, by number or name such as `POS`, scaled to the mode's SI unit |
135
+ | `get_hub_sensors` | As above | Voltage, current, temperatures, accelerometer, gyro, tilt and gesture, each in its first mode |
136
+ | `get_motor_state(port)` | As above | Speed, encoder position, absolute position and load |
137
+ | `connect_virtual_port(first_port, second_port)` | Virtual Port Setup (`0x61`) | The new pair, such as `AB`, for synchronized motor commands |
138
+ | `disconnect_virtual_port(port)` | Virtual Port Setup (`0x61`) | |
139
+
140
+ Motors (Port Output Command, `0x81`). On a pair, the `second_*` parameters give the second motor its own power,
141
+ speed or position; without them, both motors get the same value.
142
+
143
+ | Tool | Sub-commands | Notes |
144
+ | --- | --- | --- |
145
+ | `motor_start_power(port, power, second_power)` | StartPower (WriteDirectModeData mode 0), `0x02` | Unregulated, until another command |
146
+ | `motor_start_speed(port, speed, ...)` | StartSpeed `0x07`, `0x08` | Regulated, until another command; speed 0 holds the position |
147
+ | `motor_run_for_time(port, time_ms, speed, ...)` | StartSpeedForTime `0x09`, `0x0A` | Up to 32,767 ms |
148
+ | `motor_run_for_degrees(port, degrees, speed, ...)` | StartSpeedForDegrees `0x0B`, `0x0C` | The sign of speed sets the direction |
149
+ | `motor_go_to_position(port, position, speed, ...)` | GotoAbsolutePosition `0x0D`, `0x0E` | Encoder degrees |
150
+ | `motor_stop(port, end_state)` | StartPower brake or float, StartSpeed 0 to hold | Replaces the current command |
151
+ | `motor_set_acceleration_time(port, time_ms)` | SetAccTime `0x05` | Ramp for commands with `profile` `acceleration` or `both` |
152
+ | `motor_set_deceleration_time(port, time_ms)` | SetDecTime `0x06` | Ramp for commands with `profile` `deceleration` or `both` |
153
+ | `motor_preset_encoder(port, position, second_position)` | PresetEncoder (WriteDirectModeData mode 2), `0x14` | Stops the motor |
154
+
155
+ The run, turn and go-to tools also take `max_power` (0–100 %, to limit torque), `end_state` (`brake`, `float` or
156
+ `hold`), `profile` and `wait`. Speeds and powers are percentages from −100 to 100.
157
+
158
+ The light and the tilt sensor:
159
+
160
+ | Tool | Command | Notes |
161
+ | --- | --- | --- |
162
+ | `set_led_color(color)` | SetRgbColorNo | `off`, `pink`, `purple`, `blue`, `light_blue`, `cyan`, `green`, `yellow`, `orange`, `red` or `white` |
163
+ | `set_led_rgb(red, green, blue)` | SetRgbColors | 0–255 each |
164
+ | `preset_tilt_impact_count(count)` | TiltImpactPreset | Sets the counter of bumps the hub has detected |
165
+ | `configure_tilt_impact(threshold, holdoff_ms)` | TiltConfigImpact | How hard a bump must be to count, and the minimum time between two |
166
+
167
+ ## How moves end
168
+
169
+ `motor_run_for_time`, `motor_run_for_degrees` and `motor_go_to_position` wait until the motors stop, unless `wait` is
170
+ false, and return the outcome with each motor's encoder positions before and after:
171
+
172
+ - `completed`: the move ended as asked.
173
+ - `interrupted`: another command replaced it, such as `motor_stop`.
174
+ - `stalled`: a motor stopped turning (less than 2° in 1 s) before the end, so the server braked it. A motor that is
175
+ slowed but still turning is not stalled. A mechanism driven against a stop on purpose, to find its zero, ends this
176
+ way.
177
+ - `started`: `wait` was false.
178
+
179
+ The hub reports when most commands finish, but this one (firmware 1.0.00.0000) doesn't for timed runs or for the
180
+ degree moves of a pair. For those, the server takes the move as completed once its time is up, or once every motor is
181
+ within 5° of its target.
182
+
183
+ ## Good to know
184
+
185
+ - Values are read on request: `read_port_value` and the other readers put the device in the mode they need, then ask
186
+ for its value. They scale the device's raw values to its SI unit with the ranges the device reports.
187
+ - After a move that ends holding its position, the hub sometimes ignores the next command without replying. If the
188
+ hub doesn't acknowledge a motor command within 0.5 s, the server sends it once more.
189
+ - For a pair, `motor_go_to_position` with `second_position` didn't do what the protocol describes on the hub this was
190
+ tested with: the second motor moved by the first motor's distance instead of to its own target. Position motors one
191
+ at a time when exact positions matter.
192
+ - Some hub properties may be missing from `get_hub_info`: the tested hub doesn't report its hardware network family.
193
+ - Tool annotations mark the reading tools as read-only and `switch_off_hub` as destructive, so clients can ask before
194
+ running it.
195
+ - Tested on a Technic Hub with firmware 1.0.00.0000 and four Technic Large Motors (88013), from macOS: every reading
196
+ tool; `set_led_color`, `set_led_rgb` and `set_busy_indication`; `disconnect_hub`, with the reconnection that
197
+ follows, and `switch_off_hub`; and all the motor tools on single motors, plus pairs with `connect_virtual_port`,
198
+ `disconnect_virtual_port`, `motor_run_for_degrees`, `motor_run_for_time` and `motor_go_to_position`. Not tried on a
199
+ hub yet: `set_hub_name`, `reset_hub_name`, `set_port_vcc`, `preset_tilt_impact_count`, `configure_tilt_impact`,
200
+ `motor_stop` with `hold`, and the `second_power`, `second_speed` and `second_position` values of
201
+ `motor_start_power`, `motor_start_speed` and `motor_preset_encoder`.
202
+
203
+ ## Not covered
204
+
205
+ These parts of the protocol are left out on purpose:
206
+
207
+ - Firmware update and memory lock (`0x10`–`0x13`), and the production-only fast shutdown (Hub Actions `0x2F`): they can
208
+ leave the hub unusable.
209
+ - Raw WriteDirect (`0x50`), which carries the hardware reset and the tilt sensor's factory calibration: they can
210
+ de-calibrate a device.
211
+ - Hardware network commands (`0x08`) and setting the hardware network ID and family: they are for hubs connected to
212
+ each other without a computer.
213
+ - Value notifications and combined-mode sensor streams (`0x42`, `0x46`, `0x48`): the tools read values on request
214
+ instead.
215
+ - Queued commands: every output command runs immediately, replacing the port's current command.
216
+
217
+ ## Python library
218
+
219
+ The protocol and Bluetooth layers also work without MCP:
220
+
221
+ ```python
222
+ import asyncio
223
+
224
+ from technic_hub_mcp import protocol
225
+ from technic_hub_mcp.hub import TechnicHub
226
+
227
+
228
+ async def main() -> None:
229
+ hub = TechnicHub()
230
+ try:
231
+ motor = await hub.port_id("A")
232
+ result = await hub.move(protocol.start_speed_for_degrees(motor, 90, 30))
233
+ print(result.outcome, result.motors[0].end_position)
234
+ finally:
235
+ await hub.disconnect()
236
+
237
+
238
+ asyncio.run(main())
239
+ ```
240
+
241
+ - [`protocol`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/protocol.py):
242
+ builds and decodes LWP3 messages. No Bluetooth.
243
+ - [`hub`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/hub.py):
244
+ `TechnicHub` finds, connects to and reconnects to the hub, matches replies to requests and follows motor commands.
245
+ - [`models`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/models.py):
246
+ the results the tools return.
247
+ - [`server`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/server.py):
248
+ the MCP tools.
249
+
250
+ ## Development
251
+
252
+ ```bash
253
+ git clone https://github.com/gustavo-pabon/mhs-pilot.git
254
+ cd mhs-pilot/technic-hub-mcp
255
+ python3 -m venv .venv
256
+ .venv/bin/pip install -e . --group dev # needs pip 25.1 or later
257
+ .venv/bin/pytest
258
+ .venv/bin/ruff check . && .venv/bin/ruff format --check .
259
+ ```
260
+
261
+ The tests don't need a hub: they use a simulated one.
262
+
263
+ To release, update `__version__` in `src/technic_hub_mcp/__init__.py` through a pull request. Once it's merged, tag
264
+ that commit on `main` with the new version, for example `technic-hub-mcp-v0.1.1`, and push the tag. GitHub Actions
265
+ then tests the package on Python 3.10–3.14, builds it, and publishes it to PyPI after a maintainer approves the
266
+ deployment on the workflow run.
267
+
268
+ ## License
269
+
270
+ [MIT](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/LICENSE). This project is not affiliated
271
+ with or endorsed by the LEGO Group. LEGO and Technic are trademarks of the LEGO Group.
@@ -0,0 +1,243 @@
1
+ # LEGO Technic Hub MCP server
2
+
3
+ An [MCP](https://modelcontextprotocol.io) server that lets AI assistants read and control a LEGO Technic Hub (88012)
4
+ over Bluetooth LE: the motors and sensors on its four ports, its built-in sensors and its light. It implements LEGO's
5
+ [Wireless Protocol 3.0](https://lego.github.io/lego-ble-wireless-protocol-docs/) (LWP3), with tools for the hub's
6
+ properties, alerts and actions, the devices on its ports and their modes, and the port output commands.
7
+
8
+ ## Requirements
9
+
10
+ - Python 3.10 or later.
11
+ - A computer with Bluetooth LE: macOS, Linux (BlueZ) or Windows 10 or later, through
12
+ [bleak](https://github.com/hbldh/bleak).
13
+ - The hub with LEGO's own firmware. Pybricks firmware replaces LWP3, so this server can't talk to a hub that runs it.
14
+ - The hub switched on and not connected to another app or device: it accepts one connection at a time. Press its
15
+ button: the light flashes white while the hub waits for a connection and turns solid blue once connected. A hub that
16
+ nothing connects to switches itself off after a short while.
17
+
18
+ On macOS, the app that starts the server (VS Code, Claude, Terminal…) needs Bluetooth access: **System Settings →
19
+ Privacy & Security → Bluetooth**.
20
+
21
+ ## Installation
22
+
23
+ Install it from [PyPI](https://pypi.org/project/technic-hub-mcp/) into a virtual environment:
24
+
25
+ ```bash
26
+ python3 -m venv .venv
27
+ .venv/bin/pip install technic-hub-mcp
28
+ ```
29
+
30
+ This installs the `technic-hub-mcp` command in `.venv/bin/`. It runs the server over stdio. With
31
+ [uv](https://docs.astral.sh/uv/), `uvx technic-hub-mcp` runs it without installing it first.
32
+
33
+ ## Configuration
34
+
35
+ Add the command to your MCP client, using its absolute path. With uv, use `"command": "uvx"` and
36
+ `"args": ["technic-hub-mcp"]` instead.
37
+
38
+ VS Code (`.vscode/mcp.json`):
39
+
40
+ ```json
41
+ {
42
+ "servers": {
43
+ "technic-hub": {
44
+ "type": "stdio",
45
+ "command": "/absolute/path/to/.venv/bin/technic-hub-mcp"
46
+ }
47
+ }
48
+ }
49
+ ```
50
+
51
+ Claude Desktop (`claude_desktop_config.json`):
52
+
53
+ ```json
54
+ {
55
+ "mcpServers": {
56
+ "technic-hub": {
57
+ "command": "/absolute/path/to/.venv/bin/technic-hub-mcp"
58
+ }
59
+ }
60
+ }
61
+ ```
62
+
63
+ Options, passed in `args`:
64
+
65
+ | Option | Default | Description |
66
+ | --- | --- | --- |
67
+ | `--address ADDRESS` | First Technic Hub found | Bluetooth address of the hub (a UUID on macOS). Use it when several hubs are nearby. |
68
+ | `--timeout SECONDS` | `10` | How long to search for and connect to the hub. |
69
+
70
+ The server looks for a hub that advertises the LWP3 service as a Technic Hub, and connects on the first tool call. If
71
+ the connection drops, for example because the hub switched itself off, the next tool call reconnects once the hub is
72
+ on again. When the server stops, it brakes the motors and disconnects.
73
+
74
+ To try the server without an AI client, open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
75
+
76
+ ```bash
77
+ npx @modelcontextprotocol/inspector .venv/bin/technic-hub-mcp
78
+ ```
79
+
80
+ ## Tools
81
+
82
+ Tools take ports as a letter, `A` to `D`, a synchronized pair such as `AB` (see `connect_virtual_port`), or a port
83
+ number. The hub's built-in devices only have numbers; on the hub this was tested with, they are 50 (light),
84
+ 59 (current), 60 (voltage), 61 and 96 (temperature), 97 (accelerometer), 98 (gyro), 99 (tilt) and 100 (gesture).
85
+ `list_ports` shows them all.
86
+
87
+ The hub:
88
+
89
+ | Tool | Protocol message | Notes |
90
+ | --- | --- | --- |
91
+ | `get_hub_info` | Hub Properties (`0x01`) | Name, firmware and hardware versions, battery, signal, MAC addresses and the other properties, and what the hub advertised |
92
+ | `get_hub_alerts` | Hub Alerts (`0x03`) | Low voltage, high current, low signal strength and over-power condition |
93
+ | `set_hub_name(name)` | Hub Properties: Set | 1–14 printable ASCII characters. The hub keeps the name and advertises it |
94
+ | `reset_hub_name` | Hub Properties: Reset | Restores the default name |
95
+ | `set_busy_indication(enabled)` | Hub Actions `0x05`, `0x06` | Shows or clears the busy indication on the light |
96
+ | `set_port_vcc(enabled)` | Hub Actions `0x03`, `0x04` | Switches the supply voltage of the ports |
97
+ | `disconnect_hub` | Hub Actions `0x02` | The next tool call reconnects while the hub is still on |
98
+ | `switch_off_hub` | Hub Actions `0x01` | Destructive: the hub must then be switched on by hand |
99
+
100
+ Ports and sensors:
101
+
102
+ | Tool | Protocol messages | Returns |
103
+ | --- | --- | --- |
104
+ | `list_ports` | Hub Attached I/O (`0x04`) | Every port with a device: connector, built-in or virtual pair, device type and revisions |
105
+ | `get_port_info(port)` | Port Information (`0x21`, `0x43`), Port Mode Information (`0x22`, `0x44`) | The device's capabilities and, per mode: name, raw, percent and SI ranges, unit, mappings and value format |
106
+ | `read_port_value(port, mode)` | Port Input Format Setup (`0x41`), Port Value (`0x21`, `0x45`) | The values of one mode, by number or name such as `POS`, scaled to the mode's SI unit |
107
+ | `get_hub_sensors` | As above | Voltage, current, temperatures, accelerometer, gyro, tilt and gesture, each in its first mode |
108
+ | `get_motor_state(port)` | As above | Speed, encoder position, absolute position and load |
109
+ | `connect_virtual_port(first_port, second_port)` | Virtual Port Setup (`0x61`) | The new pair, such as `AB`, for synchronized motor commands |
110
+ | `disconnect_virtual_port(port)` | Virtual Port Setup (`0x61`) | |
111
+
112
+ Motors (Port Output Command, `0x81`). On a pair, the `second_*` parameters give the second motor its own power,
113
+ speed or position; without them, both motors get the same value.
114
+
115
+ | Tool | Sub-commands | Notes |
116
+ | --- | --- | --- |
117
+ | `motor_start_power(port, power, second_power)` | StartPower (WriteDirectModeData mode 0), `0x02` | Unregulated, until another command |
118
+ | `motor_start_speed(port, speed, ...)` | StartSpeed `0x07`, `0x08` | Regulated, until another command; speed 0 holds the position |
119
+ | `motor_run_for_time(port, time_ms, speed, ...)` | StartSpeedForTime `0x09`, `0x0A` | Up to 32,767 ms |
120
+ | `motor_run_for_degrees(port, degrees, speed, ...)` | StartSpeedForDegrees `0x0B`, `0x0C` | The sign of speed sets the direction |
121
+ | `motor_go_to_position(port, position, speed, ...)` | GotoAbsolutePosition `0x0D`, `0x0E` | Encoder degrees |
122
+ | `motor_stop(port, end_state)` | StartPower brake or float, StartSpeed 0 to hold | Replaces the current command |
123
+ | `motor_set_acceleration_time(port, time_ms)` | SetAccTime `0x05` | Ramp for commands with `profile` `acceleration` or `both` |
124
+ | `motor_set_deceleration_time(port, time_ms)` | SetDecTime `0x06` | Ramp for commands with `profile` `deceleration` or `both` |
125
+ | `motor_preset_encoder(port, position, second_position)` | PresetEncoder (WriteDirectModeData mode 2), `0x14` | Stops the motor |
126
+
127
+ The run, turn and go-to tools also take `max_power` (0–100 %, to limit torque), `end_state` (`brake`, `float` or
128
+ `hold`), `profile` and `wait`. Speeds and powers are percentages from −100 to 100.
129
+
130
+ The light and the tilt sensor:
131
+
132
+ | Tool | Command | Notes |
133
+ | --- | --- | --- |
134
+ | `set_led_color(color)` | SetRgbColorNo | `off`, `pink`, `purple`, `blue`, `light_blue`, `cyan`, `green`, `yellow`, `orange`, `red` or `white` |
135
+ | `set_led_rgb(red, green, blue)` | SetRgbColors | 0–255 each |
136
+ | `preset_tilt_impact_count(count)` | TiltImpactPreset | Sets the counter of bumps the hub has detected |
137
+ | `configure_tilt_impact(threshold, holdoff_ms)` | TiltConfigImpact | How hard a bump must be to count, and the minimum time between two |
138
+
139
+ ## How moves end
140
+
141
+ `motor_run_for_time`, `motor_run_for_degrees` and `motor_go_to_position` wait until the motors stop, unless `wait` is
142
+ false, and return the outcome with each motor's encoder positions before and after:
143
+
144
+ - `completed`: the move ended as asked.
145
+ - `interrupted`: another command replaced it, such as `motor_stop`.
146
+ - `stalled`: a motor stopped turning (less than 2° in 1 s) before the end, so the server braked it. A motor that is
147
+ slowed but still turning is not stalled. A mechanism driven against a stop on purpose, to find its zero, ends this
148
+ way.
149
+ - `started`: `wait` was false.
150
+
151
+ The hub reports when most commands finish, but this one (firmware 1.0.00.0000) doesn't for timed runs or for the
152
+ degree moves of a pair. For those, the server takes the move as completed once its time is up, or once every motor is
153
+ within 5° of its target.
154
+
155
+ ## Good to know
156
+
157
+ - Values are read on request: `read_port_value` and the other readers put the device in the mode they need, then ask
158
+ for its value. They scale the device's raw values to its SI unit with the ranges the device reports.
159
+ - After a move that ends holding its position, the hub sometimes ignores the next command without replying. If the
160
+ hub doesn't acknowledge a motor command within 0.5 s, the server sends it once more.
161
+ - For a pair, `motor_go_to_position` with `second_position` didn't do what the protocol describes on the hub this was
162
+ tested with: the second motor moved by the first motor's distance instead of to its own target. Position motors one
163
+ at a time when exact positions matter.
164
+ - Some hub properties may be missing from `get_hub_info`: the tested hub doesn't report its hardware network family.
165
+ - Tool annotations mark the reading tools as read-only and `switch_off_hub` as destructive, so clients can ask before
166
+ running it.
167
+ - Tested on a Technic Hub with firmware 1.0.00.0000 and four Technic Large Motors (88013), from macOS: every reading
168
+ tool; `set_led_color`, `set_led_rgb` and `set_busy_indication`; `disconnect_hub`, with the reconnection that
169
+ follows, and `switch_off_hub`; and all the motor tools on single motors, plus pairs with `connect_virtual_port`,
170
+ `disconnect_virtual_port`, `motor_run_for_degrees`, `motor_run_for_time` and `motor_go_to_position`. Not tried on a
171
+ hub yet: `set_hub_name`, `reset_hub_name`, `set_port_vcc`, `preset_tilt_impact_count`, `configure_tilt_impact`,
172
+ `motor_stop` with `hold`, and the `second_power`, `second_speed` and `second_position` values of
173
+ `motor_start_power`, `motor_start_speed` and `motor_preset_encoder`.
174
+
175
+ ## Not covered
176
+
177
+ These parts of the protocol are left out on purpose:
178
+
179
+ - Firmware update and memory lock (`0x10`–`0x13`), and the production-only fast shutdown (Hub Actions `0x2F`): they can
180
+ leave the hub unusable.
181
+ - Raw WriteDirect (`0x50`), which carries the hardware reset and the tilt sensor's factory calibration: they can
182
+ de-calibrate a device.
183
+ - Hardware network commands (`0x08`) and setting the hardware network ID and family: they are for hubs connected to
184
+ each other without a computer.
185
+ - Value notifications and combined-mode sensor streams (`0x42`, `0x46`, `0x48`): the tools read values on request
186
+ instead.
187
+ - Queued commands: every output command runs immediately, replacing the port's current command.
188
+
189
+ ## Python library
190
+
191
+ The protocol and Bluetooth layers also work without MCP:
192
+
193
+ ```python
194
+ import asyncio
195
+
196
+ from technic_hub_mcp import protocol
197
+ from technic_hub_mcp.hub import TechnicHub
198
+
199
+
200
+ async def main() -> None:
201
+ hub = TechnicHub()
202
+ try:
203
+ motor = await hub.port_id("A")
204
+ result = await hub.move(protocol.start_speed_for_degrees(motor, 90, 30))
205
+ print(result.outcome, result.motors[0].end_position)
206
+ finally:
207
+ await hub.disconnect()
208
+
209
+
210
+ asyncio.run(main())
211
+ ```
212
+
213
+ - [`protocol`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/protocol.py):
214
+ builds and decodes LWP3 messages. No Bluetooth.
215
+ - [`hub`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/hub.py):
216
+ `TechnicHub` finds, connects to and reconnects to the hub, matches replies to requests and follows motor commands.
217
+ - [`models`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/models.py):
218
+ the results the tools return.
219
+ - [`server`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/server.py):
220
+ the MCP tools.
221
+
222
+ ## Development
223
+
224
+ ```bash
225
+ git clone https://github.com/gustavo-pabon/mhs-pilot.git
226
+ cd mhs-pilot/technic-hub-mcp
227
+ python3 -m venv .venv
228
+ .venv/bin/pip install -e . --group dev # needs pip 25.1 or later
229
+ .venv/bin/pytest
230
+ .venv/bin/ruff check . && .venv/bin/ruff format --check .
231
+ ```
232
+
233
+ The tests don't need a hub: they use a simulated one.
234
+
235
+ To release, update `__version__` in `src/technic_hub_mcp/__init__.py` through a pull request. Once it's merged, tag
236
+ that commit on `main` with the new version, for example `technic-hub-mcp-v0.1.1`, and push the tag. GitHub Actions
237
+ then tests the package on Python 3.10–3.14, builds it, and publishes it to PyPI after a maintainer approves the
238
+ deployment on the workflow run.
239
+
240
+ ## License
241
+
242
+ [MIT](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/LICENSE). This project is not affiliated
243
+ with or endorsed by the LEGO Group. LEGO and Technic are trademarks of the LEGO Group.
@@ -0,0 +1,49 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "technic-hub-mcp"
7
+ dynamic = ["version"]
8
+ description = "MCP server that lets AI assistants read and control a LEGO Technic Hub and its motors over Bluetooth."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Gustavo Pabon" }]
13
+ requires-python = ">=3.10"
14
+ dependencies = ["bleak>=3.0", "mcp>=2.3"]
15
+ keywords = ["mcp", "model-context-protocol", "bluetooth", "ble", "lego", "technic", "powered-up", "lwp3", "motor"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Intended Audience :: Developers",
19
+ "Operating System :: MacOS",
20
+ "Operating System :: Microsoft :: Windows",
21
+ "Operating System :: POSIX :: Linux",
22
+ "Programming Language :: Python :: 3",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Programming Language :: Python :: 3.13",
27
+ "Programming Language :: Python :: 3.14",
28
+ "Topic :: System :: Hardware",
29
+ ]
30
+
31
+ [project.urls]
32
+ Homepage = "https://github.com/gustavo-pabon/mhs-pilot/tree/main/technic-hub-mcp"
33
+ Source = "https://github.com/gustavo-pabon/mhs-pilot"
34
+ Issues = "https://github.com/gustavo-pabon/mhs-pilot/issues"
35
+
36
+ [project.scripts]
37
+ technic-hub-mcp = "technic_hub_mcp.server:main"
38
+
39
+ [dependency-groups]
40
+ dev = ["pytest>=8", "ruff>=0.6"]
41
+
42
+ [tool.hatch.version]
43
+ path = "src/technic_hub_mcp/__init__.py"
44
+
45
+ [tool.pytest.ini_options]
46
+ testpaths = ["tests"]
47
+
48
+ [tool.ruff]
49
+ line-length = 120
@@ -0,0 +1,3 @@
1
+ """MCP server for the LEGO Technic Hub (88012) and the motors on its ports, over Bluetooth LE."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,4 @@
1
+ from .server import main
2
+
3
+ if __name__ == "__main__":
4
+ main()