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 currently provides 13 tools for account retrieval, system information, and time operations, exposing its functionality through the standard Model Context Protocol so other tools and AI assistants can interact with it programmatically.

Status: 13 MCP tools are fully implemented across account retrieval, system information, and time categories. 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

Related MCP server: TimePRO MCP Server

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

Start the MCP server for development:

mcp dev server.py          # built-in MCP development server

Or run it standalone:

uv run server.py           # running the MCP server directly via uv

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

MCP Tools

Account tools

System tools

Time tools

Architecture

The project follows a thin-client layering:

1. server.py — single-file MCP server that declares tools/resources via FastMCP

2. busybar_python_sdk — Python SDK (Git dependency) that encapsulates all Busy Bar API logic

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

┌─────────────┐     MCP/stdio      ┌──────────────────┐     SDK calls     ┌──────────────┐
│  MCP Client │ ◄────────────────► │ server.py        │                  │ Busy Bar     │
│  (AI tool)  │   FastMCP tools    │ (FastMCP binding)│                  │ Device       │
└─────────────┘                    └──────────────────┘ ◄────────────────► └──────────────┘
                                      │                              HTTP (OpenAPI)
                                busybar_python_sdk
                                 (internal lib)

What's Next

• Extend with write/mutation tools (display messages, notifications)

• Implement MCP resources for live device data streams

• Configure linting and formatting toolchain

• Add test coverage

Project status: 13 MCP tools implemented across account, system info, and time endpoints.