toio-mcp

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 指南进行安装。

步骤 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",
        "<path to toio-mcp directory>",
        "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 <path to toio-mcp directory> run server.py

使用 --scope user 可在所有项目中使用该服务；省略此标志则仅在当前项目中使用。通过 claude mcp list 确认，然后即可在任何 Claude Code 会话中使用这些工具。

与 Cline 或 Roo Code 配合使用

将以下配置添加到 MCP 设置文件中：

{
  "mcpServers": {
    "toio-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path to toio-mcp directory>",
        "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：获取已连接立方体的列表

电机工具

• 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 文件。

---

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ファイルを参照してください。