Minecraft Bedrock MCP Server

🚀 Minecraft Bedrock MCP Server

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

✨ 主な機能

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

📦 利用可能なツール

プレイヤー制御

• 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コマンドを実行

🚀 クイックスタート

前提条件

• 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クライアントの場合は、サーバー登録についてそれぞれのドキュメントを参照してください。

📚 ドキュメント

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

💻 使用例

利用可能なスクリプト

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: 接続設定中は正常です。