toio-mcp

toio-mcp

toio-mcp is a Model Context Protocol (MCP) server for toio Core Cube. It provides a set of tools to control toio Core Cubes via the MCP protocol.

Features

• Scan and connect to toio Core Cubes
• Control motors
• Control LED indicators (including repeated patterns and turning off)
• Get position information
• Play sounds (sound effects and MIDI notes)
• Get button state
• Get battery level
• Get sensor information (motion detection, posture angle, magnetic sensor)

Installation

Requirements

• Python 3.11 or higher
• toio.py
• uv
• MCP Python SDK 1.7.1 or higher

Step 1. Install uv

Follow the Getting started guide for uv to install it.

Step 2. Clone the toio-mcp repository

git clone https://github.com/comoc/toio-mcp.git
cd toio-mcp

Step 3. Install dependencies

uv sync

Usage

Usage with Claude Desktop

Open Claude Desktop's claude_desktop_config.json (Settings → Developer → Edit Config) and add:

{
  "mcpServers": {
    "toio-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path to toio-mcp directory>",
        "run",
        "server.py"
      ]
    }
  }
}

The config file lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after editing. The toio-mcp tools should appear in the tool picker.

Usage with Claude Code

Register the server with the claude mcp add CLI:

claude mcp add toio-mcp -- uv --directory <path to toio-mcp directory> run server.py

Use --scope user to make it available across all projects, or omit the flag to keep it project-local. Verify with claude mcp list and start using the tools from any Claude Code session.

Usage with Cline or Roo Code

Add the following configuration to your MCP settings file:

{
  "mcpServers": {
    "toio-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path to toio-mcp directory>",
        "run",
        "server.py"
      ],
      "alwaysAllow": [
        "add"
      ],
      "disabled": false
    }
  }
}

Available tools

Scanner tools

• scan_cubes: Scan for toio Core Cubes
• connect_cube: Connect to a toio Core Cube
• disconnect_cube: Disconnect from a toio Core Cube
• get_connected_cubes: Get a list of connected cubes

Motor tools

• motor_control: Control the motors of a toio Core Cube
• motor_stop: Stop the motors of a toio Core Cube

LED tools

• set_indicator: Set the LED color of a toio Core Cube
• set_repeated_indicator: Set repeated LED indicator patterns
• turn_off_indicator: Turn off LED indicators

Position tools

• get_position: Get the position of a toio Core Cube

Sound tools

• play_sound_effect: Play a sound effect
• play_midi: Play a MIDI note
• stop_sound: Stop sound playback

Button tools

• get_button_state: Get the button state

Battery tools

• get_battery_level: Get the battery level

Sensor tools

• get_motion_detection: Get motion detection information
• get_posture_angle: Get posture angle information
• get_magnetic_sensor: Get magnetic sensor information

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

toio-mcp (日本語)

toio-mcp は、toio Core Cube 用の Model Context Protocol (MCP) サーバーです。MCPプロトコルを通じてtoio Core Cubeを制御するためのツールセットを提供します。

特徴

• toio Core Cubeのスキャンと接続
• モーター制御
• LED制御（繰り返しパターンや消灯を含む）
• 位置情報の取得
• サウンド再生（効果音やMIDI音）
• ボタン状態の取得
• バッテリー残量の取得
• センサー情報の取得（モーション検出、姿勢角度、磁気センサー）

インストール

必要条件

• Python 3.11以上
• toio.py
• uv
• MCP Python SDK 1.7.1以上

ステップ1. uvのインストール

uvのGetting startedに従ってuvインストールしてください。

ステップ2. toio-mcpレポジトリのクローン

git clone https://github.com/comoc/toio-mcp.git
cd toio-mcp

ステップ3. 依存関係のインストール

uv sync

使用方法

Claude Desktopで使う

Claude Desktop の設定 → 開発者 → 設定を編集 から claude_desktop_config.json を開き、以下を追加します:

{
  "mcpServers": {
    "toio-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<toio-mcpディレクトリへのパス>",
        "run",
        "server.py"
      ]
    }
  }
}

設定ファイルの場所:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

編集後にClaude Desktopを再起動すると、ツール一覧に toio-mcp のツールが表示されます。

Claude Codeで使う

claude mcp add コマンドでサーバーを登録します:

claude mcp add toio-mcp -- uv --directory <toio-mcpディレクトリへのパス> run server.py

全プロジェクトで使いたい場合は --scope user を付け、現在のプロジェクトだけで使う場合はフラグなしで実行します。claude mcp list で登録確認後、Claude Code セッションからツールを呼び出せます。

ClineやRoo Codeで使う

MCPの設定ファイルに以下の設定を追加します：

{
  "mcpServers": {
    "toio-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<toio-mcpディレクトリへのパス>",
        "run",
        "server.py"
      ],
      "alwaysAllow": [
        "add"
      ],
      "disabled": false
    }
  }
}

利用可能なツール

スキャナーツール

• scan_cubes: toio Core Cubeをスキャン
• connect_cube: toio Core Cubeに接続
• disconnect_cube: toio Core Cubeから切断
• get_connected_cubes: 接続されているCubeのリストを取得

モーターツール

• motor_control: toio Core Cubeのモーターを制御
• motor_stop: toio Core Cubeのモーターを停止

LEDツール

• set_indicator: toio Core CubeのLEDの色を設定
• set_repeated_indicator: 繰り返しLEDインジケーターパターンを設定
• turn_off_indicator: LEDインジケーターを消灯

位置情報ツール

• get_position: toio Core Cubeの位置情報を取得

サウンドツール

• play_sound_effect: 効果音を再生
• play_midi: MIDI音を再生
• stop_sound: サウンド再生を停止

ボタンツール

• get_button_state: ボタンの状態を取得

バッテリーツール

• get_battery_level: バッテリー残量を取得

センサーツール

• get_motion_detection: モーション検出情報を取得
• get_posture_angle: 姿勢角度情報を取得
• get_magnetic_sensor: 磁気センサー情報を取得

ライセンス

このプロジェクトはMITライセンスの下で提供されています - 詳細はLICENSEファイルを参照してください。