home / mcp / pybittle mcp server

pyBittle MCP Server

MCP Server to control pyBittle via BLE

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "cluesang-pybittle-mcp-server": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--port",
        "8080",
        "--",
        "uv",
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "git+https://github.com/cluesang/pyBittle.git",
        "mcp",
        "run",
        "./server.py"
      ],
      "env": {
        "JAVA_HOME": "/usr/lib/jvm/java-11-openjdk",
        "PYTHONPATH": "/path/to/project"
      }
    }
  }
}

You can control a Bittle robot over Bluetooth using an MCP server that exposes movement and pose commands. This server lets you issue actions remotely from any MCP-compatible client, making it easy to automate and orchestrate Bittle’s behavior from programs or tooling that understand MCP.

How to use

To start, ensure your Bittle robot is powered on and in Bluetooth pairing mode. Your MCP client can discover available commands on the server and invoke them to move, pose, or interact with Bittle. Typical commands include moving forward or backward, turning, sitting, and resting. Use an MCP client to call commands such as moving forward, sitting, or resting, and observe the responses and state changes in your client and the log.

How to install

Prerequisites you need on your machine: Python 3.10+, the uv package manager, and a Bittle robot with Bluetooth enabled.

Step 1: Install uv for fast, reliable Python package management.

curl -Ls https://astral.sh/uv/install.sh | sh

Step 2: Install uvx, which enables MCP server features.

curl -Ls https://astral.sh/uvx/install.sh | sh

Step 3: Install dependencies. You have two options.

# Option 1: Using start_server.sh (recommended)
chmod +x start_server.sh
./start_server.sh

# Option 2: Manual installation
uv pip install -r requirements.txt
# or, if using pyproject.toml:
uv pip install -r pyproject.toml

Step 4: Start the MCP server. You have two options.

# Option 1: Using start_server.sh (recommended)
./start_server.sh

# Option 2: Manual start
uvx mcpo --port 8080 -- uv run --with 'mcp[cli]' --with git+https://github.com/cluesang/pyBittle.git mcp run ./server.py

Additional notes

The server logs status and activity to bittle_mcp.log, helping you diagnose connection and command issues. Ensure Bluetooth pairing is stable and that no other process is using the Bittle connection.

Troubleshooting

If the server fails to connect to Bittle, verify Bluetooth pairing and ensure only one process is using the Bittle connection at a time. Check bittle_mcp.log for detailed errors. If you encounter port conflicts, the startup script will handle terminating existing server processes. Confirm that both uv and uvx are installed and available in your PATH.

Available tools

move_forward

Move the robot forward by a defined amount or duration, depending on the command implementation.

sit

Command Bittle to assume a sitting pose.

rest

Command Bittle to return to a resting state or idle pose.