pyBittle-mcp-server
A Python MCP (Model Context Protocol) server for controlling the Bittle robot via Bluetooth. This server exposes a set of commands to move, pose, and interact with Bittle using the MCP protocol.
Features
- Connects to Bittle via Bluetooth
- Exposes movement and pose commands (forward, backward, turn, sit, rest, etc.)
- Integrates with MCP tools for remote and programmatic control
- Logs all activity to
bittle_mcp.log
Requirements
- Python 3.10+
- uv for package management
- Bittle robot with Bluetooth enabled
- pyBittle library
- mcp-server library
Installation & Setup
-
Install uv (recommended for fast, reliable Python package management):
curl -Ls https://astral.sh/uv/install.sh | sh -
Install uvx (required for MCP server):
curl -Ls https://astral.sh/uvx/install.sh | sh -
Install dependencies:
# 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
Usage
-
Configure Bluetooth: Ensure your Bittle robot is powered on and in Bluetooth pairing mode.
-
Run the MCP server:
# 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.pyThe server will attempt to connect to Bittle and log status to
bittle_mcp.log. -
Integrate with MCP tools:
- This server exposes commands via the MCP protocol, making them accessible to any MCP-compatible client or tool.
- You can use the MCP CLI or other MCP tools to discover and invoke available commands on your Bittle robot.
- Example (using MCP CLI):
mcp call move_forward mcp call sit mcp call rest - All available commands are decorated with
@mcp.tool()inserver.pyand are automatically registered with the MCP server.
Development
- The main logic is in
server.py. - Logging is configured to output to both console and
bittle_mcp.log. - Commands are decorated with
@mcp.tool()for MCP exposure. - Use
start_server.shfor development as it handles environment setup and process management.
Troubleshooting
- If the server fails to connect, check Bluetooth pairing and ensure no other process is using the Bittle connection.
- Review
bittle_mcp.logfor detailed error messages. - If you encounter port conflicts,
start_server.shwill automatically handle killing existing server processes. - Make sure both
uvanduvxare installed and available in your PATH.
License
MIT License