pyBittle-mcp-server
About
pyBittle-mcp-server is a Python MCP (Model Context Protocol) server for controlling the Bittle robot via Bluetooth. It exposes movement and pose commands such as forward, backward, turn, sit, and rest, making them accessible through any MCP‑compatible client.
Details
- Author
- cluesang
- Downloads
- 125
- Categories
- Other
Jump to
- 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.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
pyBittle-mcp-serverCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install uv and uvx, then set up dependencies using the provided start_server.sh script or by manually running uv pip install -r requirements.txt. Power on the Bittle robot in Bluetooth pairing mode and start the server with ./start_server.sh. Once running, use MCP tools (e.g., the MCP CLI) to invoke commands like mcp call move_forward.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"pybittle-mcp-server": {
"pyBittle-mcp-server": {
"command": "uv",
"args": [
"pip",
"install",
"-r",
"requirements.txt"
]
}
}
}
}McpServers
{
"pyBittle-mcp-server": {
"command": "uv",
"args": [
"pip",
"install",
"-r",
"requirements.txt"
]
}
}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
1. Install uv (recommended for fast, reliable Python package management):
curl -Ls https://astral.sh/uv/install.sh | sh
2. Install uvx (required for MCP server):
curl -Ls https://astral.sh/uvx/install.sh | sh
3. 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
1. Configure Bluetooth:
Ensure your Bittle robot is powered on and in Bluetooth pairing mode.
2. 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.py
The server will attempt to connect to Bittle and log status to
bittle_mcp.log.
3. 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() in server.py and 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.sh for 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.log for detailed error messages.
- If you encounter port conflicts, start_server.sh will automatically handle killing existing server processes.
- Make sure both uv and uvx are installed and available in your PATH.
License
MIT License
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
