Busy Bar MCP Server

A Python MCP server written with FastMCP that wraps the busybar_python_sdk to communicate with a physical Busy Bar device over HTTP. The Busy Bar is a digital time-management display — this MCP server provides 32 tools for account retrieval, system information, time operations, BLE control, and input events, exposing its functionality through the standard Model Context Protocol so other tools and AI assistants can interact with it programmatically.

Status: 32 MCP tools are fully implemented across account retrieval, system information, time operations, device state queries, BLE control, and input events, with a complete test suite documented in this README. The project is ready to use — see the What's Next section below for planned work.

Prerequisites

• Python ≥ 3.12 — the project pins Python 3.12+ (see .python-version)
• uv — dependency manager and virtual environment resolver

Installation

Clone the repository and install dependencies:

uv sync

This creates a virtual environment and installs all packages declared in pyproject.toml (including busybar_python_sdk).

Configuration

Copy the example .env.example file (if present) to create your own .env at the project root with the following variables.

BUSYBAR_API_TOKEN=my-super-secret-token
BUSYBAR_BASE_URL=10.0.4.20

It is also possible to declare the variables before starting the server:

export BUSYBAR_API_TOKEN=my-super-secret-token && export BUSYBAR_BASE_URL=10.0.4.20 

Usage

Set the BUSYBAR_API_TOKEN and BUSYBAR_BASE_URL environment variables (or place them in a .env file in the working directory), then start the MCP server:

# One-shot run via uvx (no local install required)
BUSYBAR_API_TOKEN=… BUSYBAR_BASE_URL=10.0.4.20 uvx busybar-mcp

# Or install locally and run the console script
uv sync
BUSYBAR_API_TOKEN=… BUSYBAR_BASE_URL=10.0.4.20 busybar-mcp

# Development (built-in MCP dev server / inspector)
uv sync
BUSYBAR_API_TOKEN=… BUSYBAR_BASE_URL=10.0.4.20 mcp dev -- uvx busybar-mcp

python -m busybar_mcp is equivalent to the console script and starts the same stdio server.

Once started, clients can connect to the server using their MCP transport.

MCP Tools

Account tools

System tools

Time tools

Device Status & Configuration

Input tools

Architecture

The project follows a thin-client layering:

1. busybar_mcp — the package and its main entry point (busybar_mcp/__init__.py): loads .env, registers all tool modules on import, and calls server.run(transport="stdio")
2. busybar_mcp/ — modularized MCP tools organized by Busy Bar API namespace:

┌───────────────────────────────┐      MCP/stdio       ┌──────────────────┐      SDK calls     ┌──────────────┐
│           MCP Client          │ ◄──────────────────► │ busybar_mcp      │                    │ Busy Bar     │
│         (AI tool)             │   FastMCP tools      │ (pkg + entry pt) │ ◄────────────────► │ Device       │
└───────────────────────────────┘                      └──────────────────┘                    └──────────────┘
                               busybar_mcp/  (package with 10 namespace modules + utils)   HTTP (OpenAPI)
                                                                                           busybar_python_sdk

• busybar_mcp/account.py — account retrieval tools
• busybar_mcp/system.py — system information tools
• busybar_mcp/time.py — time operations tools
• busybar_mcp/ble.py — BLE module tools
• busybar_mcp/input.py — input event tools
• busybar_mcp/busy.py — busy timer tools
• busybar_mcp/settings.py — device settings tools
• busybar_mcp/smarthome.py — smart home tools
• busybar_mcp/storage.py — storage management tools
• busybar_mcp/updater.py — firmware update tools
• busybar_mcp/wifi.py — Wi-Fi status tools
• busybar_mcp/utils.py — shared utilities (_serialize, _wrap_tool_error)

3. HTTP → Busy Bar device — the SDK communicates with the device over HTTP using the OpenAPI schema defined in openapi.yaml

Testing

A working test suite is included with the project. The convenience runner at run_tests.py invokes pytest against the tests/ directory with sensible defaults and no-header output.

Run basic tests

python run_tests.py

Run with coverage output

COVERAGE=1 python run_tests.py

Coverage is reported via pytest-cov (--cov=busybar_mcp --cov-report=term-missing).

Test Coverage Summary

• 32 MCP tools tested — one parametrized happy-path test per tool across account, system info, time, BLE, busy timer, settings, smart home, storage, update, wifi, and input categories.
  • Per-module test files: tests/test_account.py, tests/test_system.py, tests/test_time.py, tests/test_ble.py, tests/test_busy.py, tests/test_settings.py, tests/test_smarthome.py, tests/test_storage.py, tests/test_updater.py, tests/test_wifi.py, tests/test_input.py
• Error-path tests verify behaviour when the Busy Bar device is missing or unreachable (mocked HTTP failures).
• Missing environment variable tests confirm that absent BUSYBAR_BASE_URL / BUSYBAR_API_TOKEN are handled gracefully.
• conftest fixtures:
  • clear_env_vars — temporarily removes BUSYBAR_BASE_URL and BUSYBAR_API_TOKEN from os.environ (restoring originals afterward).
• Serialization tests (tests/test_serialization.py) verify _serialize() handles SDK models, dicts, lists, scalars, and edge cases correctly.

What's Next

• Extend with additional write/mutation tools (display messages, notifications)
• Implement MCP resources for live device data streams
• Configure linting and formatting toolchain