Minecraft Bedrock MCP Server

🚀 Minecraft Bedrock MCP Server

このサーバーは、TypeScriptで構築されたMCP（Model Context Protocol）サーバーです。WebSocket接続を介してMinecraft Bedrock Editionを制御するためのツールを提供します。

🚀 クイックスタート

前提条件

• Node.js 16以上
• チートを有効にしたMinecraft Bedrock Edition
• MCPクライアント（例: Claude Desktop, Continueなど）

インストール

1. リポジトリをクローンする

git clone https://github.com/Mming-Lab/minecraft-bedrock-mcp-server.git
cd minecraft-bedrock-mcp-server

2. 依存関係をインストールする

npm install

3. プロジェクトをビルドする

npm run build

4. サーバーを起動する

npm start

Minecraftへの接続

1. MCPサーバーを起動する

npm start

デフォルトのポート: 8001

2. Minecraftワールドを準備する

   • チートを有効にしたワールドを作成または選択します。
   • すべての実験的機能を無効にします。
   • 最適な結果を得るにはクリエイティブモードを使用します。

3. Minecraftから接続する Minecraft Bedrock Editionのチャットで以下のコマンドを実行します。

/connect localhost:8001/ws

4. 接続を確認する MCPサーバーのコンソールに接続ログが表示されるはずです。

MCPクライアントの設定 (例: Claude Desktop)

このサーバーはMCP（Model Context Protocol）標準を実装しており、互換性のあるMCPクライアントと共に使用できます。

例: Claude Desktopの設定

1. 設定ファイルを見つける

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

2. サーバー設定を追加する

{
  "mcpServers": {
    "minecraft-bedrock-mcp-server": {
      "command": "node",
      "args": ["path/to/dist/server.js"]
    }
  }
}

3. カスタムポート設定

{
  "mcpServers": {
    "minecraft-bedrock-mcp-server": {
      "command": "node",
      "args": ["path/to/dist/server.js", "--port=8002"]
    }
  }
}

4. MCPクライアントを再起動する 新しい設定を読み込むためにMCPクライアントを再起動します。

他のMCPクライアントの場合は、それぞれのドキュメントを参照してサーバー登録を行ってください。

✨ 主な機能

• 13の強力なツールが階層システムで整理されています。
• レベル1の基本ツール：プレイヤー制御、エージェント(@c)操作、ワールド操作
• レベル2の高度なツール：複雑な建築操作、高度なワールド管理
• MCPクライアント統合（例: Claude Desktop）によるAIベースのMinecraft自動化
• 型安全なTypeScript実装で、包括的なエラーハンドリングが行われます。

📦 インストール

上記の「クイックスタート」の「インストール」セクションを参照してください。

💻 使用例

基本的な使用法

# リポジトリをクローンする
git clone https://github.com/Mming-Lab/minecraft-bedrock-mcp-server.git
cd minecraft-bedrock-mcp-server

# 依存関係をインストールする
npm install

# プロジェクトをビルドする
npm run build

# サーバーを起動する
npm start

高度な使用法

// カスタムポートでサーバーを起動する設定
{
  "mcpServers": {
    "minecraft-bedrock-mcp-server": {
      "command": "node",
      "args": ["path/to/dist/server.js", "--port=8002"]
    }
  }
}

📚 ドキュメント

貢献者や開発者向けの包括的なドキュメントが用意されています。詳細なセットアップガイドやアーキテクチャドキュメントについては、メンテナに問い合わせてください。

🔧 技術詳細

利用可能なスクリプト

npm run build    # TypeScriptをJavaScriptにコンパイルする
npm start        # コンパイルされたサーバーを起動する
npm run dev      # ビルドと起動を1つのコマンドで実行する

ポート設定

サーバーのポートはコマンドライン引数で設定できます。

• --port=8002 - カスタムポートを設定する
• デフォルト: 8001

プロジェクト構造

src/
├── server.ts              # メインサーバーの実装
├── types.ts               # TypeScriptの型定義
└── tools/                 # ツールの実装
    ├── base/tool.ts       # 抽象基底クラス
    ├── player/            # プレイヤー制御ツール
    ├── agent/             # エージェント制御ツール
    ├── world/             # ワールド操作ツール
    └── build/             # 建築ツール

🤝 貢献方法

1. リポジトリをフォークする
2. 機能ブランチを作成する (git checkout -b feature/amazing-feature)
3. 変更をコミットする (git commit -m 'Add amazing feature')
4. ブランチにプッシュする (git push origin feature/amazing-feature)
5. プルリクエストを作成する

📄 ライセンス

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

🙏 謝辞

• MCP Protocol の仕様に感謝します。
• Sandertv/mcwss のWebSocketプロトコル解析とメッセージ構造の参照に感謝します。

⚠️ 重要提示

• Minecraft Bedrock Edition でチートを有効にする必要があります。
• ワールド設定で WebSocket接続 を有効にする必要があります。
• コマンド実行には 適切な権限を持つワールド が必要です。

🔧 トラブルシューティング

接続問題

サーバーが起動しない場合

• Node.js 16以上がインストールされていることを確認してください。
• ポート8001が既に使用されていないか確認してください: netstat -ano | findstr :8001
• --port=8002 で別のポートを試してみてください。

Minecraftへの接続が失敗する場合

1. ワールド設定を確認する
   • チートが有効になっていることを確認してください。
   • すべての実験的機能を無効にしてください。
   • クリエイティブモードを使用してください。
2. 接続コマンドを確認する

/connect localhost:8001/ws

3. ファイアウォール設定を確認する
   • Windows Defenderでポート8001が許可されていることを確認してください。
   • ウイルス対策ソフトが接続をブロックしていないことを確認してください。

MCPクライアントの統合に問題がある場合

1. 設定ファイルのパスと構文を確認する（例: Claude Desktop）
2. MCPクライアントを完全に再起動する
3. サーバーログでMCPプロトコルのエラーを確認する
4. 設定ファイル内のファイルパスが絶対パスであることを確認する

一般的なエラーメッセージ

• EADDRINUSE: ポートが既に使用されています - 別のポートを試してください。
• Connection refused: サーバーが起動していないか、ポートが間違っています。
• unknown message purpose ws:encrypt: 接続設定中の正常なメッセージです。

🛠️ 利用可能なツール

プレイヤー制御

• player_position - プレイヤーの現在位置を取得する
• player_move - プレイヤーを座標に移動/テレポートする
• player_say - プレイヤーとしてメッセージを送信する

エージェント制御 (Education Edition)

• agent_move - エージェントを方向または座標に移動する ✅
• agent_turn - エージェントを左/右に回転させる、または特定の回転を設定する ✅
• agent_attack - ❌ Bedrock Editionではサポートされていません。
• agent_block_action - ❌ Bedrock Editionではサポートされていません。

ワールド操作

• world_block - ワールドブロックの操作（設定、取得、破壊）
• world_fill - 高度なオプションで領域を埋める
• world_time_weather - 時間と天候を制御する

建築ツール

• build_cube - 中実または中空の立方体を構築する
• build_line - 点間に直線を構築する
• build_sphere - 中実または中空の球体を構築する

基本的な通信

• send_message - チャットメッセージを送信する
• execute_command - 任意のMinecraftコマンドを実行する