mcpField
P
pyBittle-mcp-server

pyBittle-mcp-server

Local
github.com/cluesangOther0Updated 73w ago
Repository

About pyBittle-mcp-server

pyBittle-mcp-server is a Python MCP server for controlling the Bittle robot over Bluetooth. It exposes movement and pose commands for MCP-compatible clients and logs activity to a file and the console.

Key features

  1. 01Bluetooth connection to Bittle
  2. 02Movement and pose commands
  3. 03MCP tools for remote control
  4. 04Console and file logging

Use cases

  1. 01Move Bittle through MCP commands
  2. 02Set Bittle to poses such as sit or rest
  3. 03Review connection and command logs

MCP support

The server exposes Bittle movement and pose commands as MCP tools for compatible clients to discover and invoke.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

No install method listed yet

We haven’t collected a package or remote endpoint for this server. Follow the instructions in the project README.

Repository

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.