BOOKOO Themis Ultra MCP server

An MCP server that lets AI assistants read and control a BOOKOO Themis Ultra scale over Bluetooth LE. It covers every data packet and command in BOOKOO's official Bluetooth protocol, with one tool per protocol entry.

Requirements

• Python 3.10 or later.
• A computer with Bluetooth LE: macOS, Linux (BlueZ) or Windows 10 or later, through bleak.
• The scale switched on, in range and not connected to another app, such as the BOOKOO app. It accepts one connection at a time.

On macOS, the app that starts the server (VS Code, Claude, Terminal…) needs Bluetooth access: System Settings → Privacy & Security → Bluetooth.

Installation

Install it from PyPI into a virtual environment:

python3 -m venv .venv
.venv/bin/pip install bookoo-themis-ultra-mcp

This installs the bookoo-themis-ultra-mcp command in .venv/bin/. It runs the server over stdio. With uv, uvx bookoo-themis-ultra-mcp runs it without installing it first.

Configuration

Add the command to your MCP client, using its absolute path. With uv, use "command": "uvx" and "args": ["bookoo-themis-ultra-mcp"] instead.

VS Code (.vscode/mcp.json):

{
  "servers": {
    "bookoo-themis-ultra": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/bookoo-themis-ultra-mcp"
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "bookoo-themis-ultra": {
      "command": "/absolute/path/to/.venv/bin/bookoo-themis-ultra-mcp"
    }
  }
}

Options, passed in args:

The server looks for a scale advertising a name that starts with BOOKOO_SC_U and connects on the first tool call. If the connection drops, for example because the scale turned itself off, the next tool call reconnects once the scale is back on.

To try the server without an AI client, open it in the MCP Inspector:

npx @modelcontextprotocol/inspector .venv/bin/bookoo-themis-ultra-mcp

Tools

Data the scale sends:

Commands (03 0A):

Good to know:

• The scale does not acknowledge commands. Call get_scale_data afterwards to check the effect, for example that the weight is zero after tare or that the beep level changed. Changes show up within a fraction of a second.
• The firmware version can't be read over Bluetooth, so the server can't check firmware requirements. The BOOKOO app shows the version.
• get_powder_weight and get_auto_mode_event return the last value the scale sent since the server connected.
• Tool annotations mark the get_* tools as read-only and calibrate and shut_down as destructive, so clients can ask before running them.
• Tested on a Themis Ultra from macOS: get_scale_data, set_beep_level, set_flow_smoothing, set_auto_off_time, tare, shut_down, and reconnecting after the scale was switched off and on. The other tools follow the protocol document but haven't been tried on a scale yet; the scale sent no powder-weight or automatic-mode packets during testing.

Python library

The protocol and Bluetooth layers also work without MCP:

import asyncio

from bookoo_themis_ultra_mcp import protocol
from bookoo_themis_ultra_mcp.scale import BookooScale


async def main() -> None:
    scale = BookooScale()
    try:
        print((await scale.read()).weight_g)
        await scale.send(protocol.tare())
    finally:
        await scale.disconnect()


asyncio.run(main())

• protocol: builds commands and decodes data packets. No Bluetooth.
• scale: BookooScale finds, connects to and reconnects to the scale.
• server: the MCP tools.

Development

git clone https://github.com/gustavo-pabon/mhs-pilot.git
cd mhs-pilot/bookoo-themis-ultra-mcp
python3 -m venv .venv
.venv/bin/pip install -e . --group dev   # needs pip 25.1 or later
.venv/bin/pytest
.venv/bin/ruff check . && .venv/bin/ruff format --check .

The tests don't need a scale.

To release, update __version__ in src/bookoo_themis_ultra_mcp/__init__.py and push a tag named after it, for example bookoo-themis-ultra-mcp-v0.1.0. GitHub Actions then tests the package on Python 3.10–3.14, builds it and publishes it to PyPI.

License

MIT. This project is not affiliated with or endorsed by BOOKOO.