toio-mcp

自然言語で toio ロボットキューブを制御する MCP サーバー。 toio.js 経由で BLE 接続した toio を、Claude Desktop や MCP 対応クライアントから操作できる。

前提条件

• Node.js 20 以上
• Bluetooth 4.0 (BLE) 対応 の PC
• toio Core Cube （実機が必要）

Windows の場合

toio.js が依存する noble のネイティブモジュールをビルドするため、以下が追加で必要である。

1. Visual Studio Build Tools 2022 — 「C++ によるデスクトップ開発」ワークロードを選択してインストールする
2. Python 3 — node-gyp が使用する

package.json の overrides で noble を Windows WinRT BLE 対応の @abandonware/noble に差し替えている。

セットアップ

cd toio-mcp
npm install
npm run build

WebAPI サーバー

stackchan などの外部デバイスから自然言語で toio を操作するための WebAPI サーバーを内蔵している。 自然言語テキストを LLM（Claude / OpenAI）が解釈し、toio の操作に変換して実行する。

環境変数の設定

.env.example をコピーして .env を作成し、API キーを設定する。

cp .env.example .env

.env の内容:

# LLM プロバイダ（claude または openai）
LLM_PROVIDER=claude

# Claude API を使う場合
ANTHROPIC_API_KEY=sk-ant-...

# OpenAI API を使う場合
# OPENAI_API_KEY=sk-...

# モデル名（省略時はデフォルト値を使用）
# LLM_MODEL=claude-sonnet-4-20250514

# WebAPI サーバーのポート番号
PORT=3000

WebAPI の起動

npm run dev:web    # 開発モード（tsx で直接実行）
npm run start:web  # ビルド済みファイルで起動

エンドポイント

メソッド	パス	説明	リクエストボディ
GET	/api/health	ヘルスチェック	なし
POST	/api/chat	自然言語で制御	{ "message": "前に進んで" }
POST	/api/tools/:name	LLM を介さず直接制御	ツール引数の JSON

リクエスト例

# 自然言語で制御
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "前に進んで"}'

# 直接ツール呼び出し
curl -X POST http://localhost:3000/api/tools/move \
  -H "Content-Type: application/json" \
  -d '{"left": 50, "right": 50, "duration": 1000}'

MCP サーバーの起動方法

1. Claude Desktop から使う（推奨）

Claude Desktop の設定ファイル claude_desktop_config.json に以下を追加する。 args のパスは実際のインストール先に合わせて変更すること。

{
  "mcpServers": {
    "toio": {
      "command": "node",
      "args": ["/path/to/toio-mcp/dist/index.js"]
    }
  }
}

設定後、Claude Desktop を再起動すると toio ツールが利用可能になる。

2. Claude Code から使う

Claude Code の MCP 設定（.claude/settings.json など）に同様のサーバー定義を追加する。

3. 開発モードで起動する

ビルドなしで直接実行する場合は以下を使用する。

npm run dev

4. MCP Inspector でテストする

MCP Inspector を使って各ツールを対話的にテストできる。

npm run inspect

使い方

1. MCP クライアント（Claude Desktop など）から connect ツールを呼び出し、toio cube に BLE 接続する
2. move, spin, set_led などのツールで cube を操作する
3. 操作が終わったら disconnect で切断する

MCP ツール一覧

ツール名	引数	動作
connect	なし	最寄りの cube に BLE 接続
disconnect	なし	切断
move	left, right (-115〜115), duration (ms)	左右モーター制御
stop	なし	停止
spin	speed (-115〜115), duration (ms)	その場で回転
set_led	r, g, b (0-255), duration? (ms)	LED 色変更
play_preset_sound	soundId (0-10)	内蔵効果音を再生
get_battery	なし	バッテリー残量を取得

技術スタック

• TypeScript
• Node.js ≥ 20
• @toio/scanner + @toio/cube
• @modelcontextprotocol/sdk
• zod