Fundamental Labs/Minecraft Client

Fundamental Labs/Minecraft Client

このライブラリは、Minecraft のゲームスキルおよび MCP 統合向けのクライアントライブラリです。

Fairies MCP Client（https://fairies.ai/）は、ワンクリックでの直接接続にも対応しています。

特長

• Minecraft を完全に操作：AI エージェントを Minecraft サーバーに接続し、ボットを操作します
• 検証済みスキル 30 種類：一般的な Minecraft のタスク向けに、事前に構築・テストされたスキルです
• 柔軟な接続：ボットごとのオプション設定を使用して、任意の Minecraft サーバーに接続できます
• 複数ボットのサポート：複数のボットを同時に管理できます
• MCP 標準：あらゆる MCP クライアント（Claude Desktop など）と互換性があります

インストール

npx から直接呼び出す（推奨）

npx --y -- @fundamentallabs/minecraft-mcp

npm 経由（推奨）

npm install -g @fundamentallabs/minecraft-mcp

ソースから

git clone https://github.com/FundamentalLabs/minecraft-mcp.git
cd minecraft-mcp/minecraft-client/mcp-server
npm install
npm run build

使用方法

サーバーの起動

オプションでデフォルトの接続設定を指定して、MCP サーバーを起動できます。

# Start with no defaults (connection specified per bot)
minecraft-mcp

# Start with default connection settings
minecraft-mcp -h play.example.com -p 25565

コマンドラインオプション

Options:
  -p, --port <port>  Minecraft server port (default: 25565)
  -h, --host <host>  Minecraft server host (default: localhost)
  --help            Display help

Claude Desktop またはローカルの JSON 設定との統合

Claude Desktop の設定（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

リモートインストールの場合（推奨）

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": ["-y", "-- @fundamentallabs/minecraft-mcp"]
    }
  }
}

ソースからローカルで実行する場合：

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

/path/to/minecraft-mcp を、リポジトリをクローンした実際のパスに置き換えてください。

その他の MCP クライアントとの統合

サーバーは stdio トランスポートを使用しており、あらゆる MCP クライアントと統合できます。

# Using the MCP inspector for testing
cd minecraft-client/mcp-server
npx @modelcontextprotocol/inspector node dist/mcp-server.js -- -p 25565

使用可能なスキル

ボット管理

• joinGame - Minecraft のゲームに新しいボットをスポーンします

  • username（必須）：ボットのユーザー名
  • host（任意）：サーバーのホスト（デフォルトは localhost またはコマンドラインオプション）
  • port（任意）：サーバーのポート（デフォルトは 25565 またはコマンドラインオプション）

• leaveGame - ボットをゲームから切断します

  • username（任意）：切断する特定のボット
  • disconnectAll（任意）：true の場合、すべてのボットを切断します

移動とナビゲーション

• goToSomeone - 別のプレイヤーのもとへ移動します
• goToKnownLocation - 指定した座標へ移動します
• runAway - 脅威から逃げます
• swimToLand - 水中にいるとき、最も近い陸地まで泳ぎます

戦闘と狩猟

• attackSomeone - プレイヤー、モブ、または動物を攻撃します
• hunt - 動物またはモブを狩ります

リソースの収集

• mineResource - 指定したブロックまたはリソースを採掘します
• harvestMatureCrops - 農地から成熟した作物を収穫します
• pickupItem - 地面にあるアイテムを拾います

クラフトと精錬

• craftItems - 作業台を使ってアイテムをクラフトします
• cookItem - かまどでアイテムを調理します
• smeltItem - かまどでアイテムを精錬します
• retrieveItemsFromNearbyFurnace - 近くのかまどから精錬済みアイテムを取り出します

インベントリ管理

• openInventory - ボットのインベントリを開きます
• equipItem - 防具、ツール、または武器を装備します
• dropItem - インベントリからアイテムを落とします
• giveItemToSomeone - 別のプレイヤーにアイテムを渡します

建築と農業

• placeItemNearYou - ボットの近くにブロックを設置します
• prepareLandForFarming - 農業用に土地を整えます
• useItemOnBlockOrEntity - ブロックまたはエンティティにアイテムを使用します

サバイバル

• eatFood - 空腹を回復するために食べ物を食べます
• rest - 体力を回復するために休みます
• sleepInNearbyBed - ベッドを見つけて眠ります

保管

• openNearbyChest - 近くのチェストを開きます

お楽しみ

• dance - ボットを踊らせます

視界

• lookAround - 周囲を見回して環境を観察します

コミュニケーション

• readChat - サーバーの最近のチャットメッセージを読み取ります
• sendChat - サーバーにチャットメッセージまたはコマンドを送信します

建築

• buildSomething - Minecraft のコマンドを使って構造物を建築します（チートまたはオペレーター権限が必要です）。静的なコマンド配列と動的な JavaScript コードの両方に対応しています。
• buildPixelArt - 画像から Minecraft 内にピクセルアートを作成します（チートまたはオペレーター権限が必要です）。画像を色付きブロックで構成されるピクセルアートに変換します。最大サイズは 256x256 ブロックです。

API の例

MCP クライアントと統合すると、次のようにボットを操作できます。

// First, spawn a bot
await client.callTool('joinGame', { username: 'MyBot' });

// Make the bot mine some wood
await client.callTool('mineResource', { name: 'oak_log', count: 10 });

// Craft wooden planks
await client.callTool('craftItems', { item: 'oak_planks', count: 40 });

// Navigate to coordinates
await client.callTool('goToKnownLocation', { x: 100, y: 64, z: 200 });

// Build a structure using commands (requires cheats) - Script mode
await client.callTool('buildSomething', {
  buildScript: [
    { command: "fill", x1: 0, y1: 64, z1: 0, x2: 10, y2: 64, z2: 10, block: "stone" },
    { command: "fill", x1: 1, y1: 65, z1: 1, x2: 9, y2: 68, z2: 9, block: "oak_planks" },
    { command: "setblock", x: 5, y: 65, z: 1, block: "oak_door" }
  ]
});

// Build dynamically with JavaScript (requires cheats) - Code mode
await client.callTool('buildSomething', {
  code: `
    // Build a pyramid centered on the bot
    const size = 10;
    for (let y = 0; y < size; y++) {
      const level = size - y;
      fill(pos.x - level, pos.y + y, pos.z - level,
           pos.x + level, pos.y + y, pos.z + level, 'sandstone');
      await wait(5); // Small delay between levels
    }
    log('Pyramid complete!');
  `
});

// Build pixel art from an image (requires cheats)
await client.callTool('buildPixelArt', {
  imagePath: 'https://example.com/logo.png',
  width: 64,
  height: 64,
  x: 0,
  y: 80,
  z: 100,
  facing: 'north'
});

// Read recent chat messages
await client.callTool('readChat', {
  count: 30,
  timeLimit: 300,  // Last 5 minutes
  filterType: 'chat'  // Only player messages
});

// Send a chat message
await client.callTool('sendChat', {
  message: 'Hello everyone! I am a bot.'
});

// Send a command
await client.callTool('sendChat', {
  message: '/time set day'
});

// Send a whisper
await client.callTool('sendChat', {
  message: '/msg Steve I can help you build!',
  delay: 1000  // Wait 1 second before sending
});

アーキテクチャ

MCP サーバーは次の機能を備えています。

• AI クライアントとの通信に stdio トランスポートを使用します
• 検証済みスキルディレクトリからスキルを動的に読み込みます
• 複数のボットインスタンスを管理します（現在はすべての操作で最初のボットを使用します）
• すべてのボット操作に統一されたインターフェースを提供します

要件

• Node.js >= 18.0.0
• 接続先の Minecraft サーバー（Java Edition）
• MCP 対応クライアント（Claude Desktop など）

トラブルシューティング

「Skill implementation not found」エラー

MCP サーバーは、スキルをビルドしたクローン済みリポジトリから実行する必要があります。次の点を確認してください。

1. リポジトリ全体をクローンした
2. minecraft-client ディレクトリで npm install を実行した
3. minecraft-client ディレクトリで npm run build を実行した
4. MCP サーバーを正しいディレクトリから実行している

ボットが接続できない

• Minecraft サーバーが稼働しており、アクセス可能であることを確認してください
• ポートとホストが正しいことを確認してください
• サーバーがボットの使用する Minecraft バージョンを許可していることを確認してください

スキルが機能しない

• スキルを使用する前に、ボットが正常にスポーンしたことを確認してください
• 一部のスキルには特定のアイテムや条件が必要です
• ボットのコンソール出力にエラーメッセージがないか確認してください

貢献

貢献を歓迎します！お気軽に Pull Request を送信してください。

ライセンス

MIT - 詳細は LICENSE ファイルをご覧ください

サポート

問題の報告や機能のリクエストには、GitHub issue trackerをご利用ください。

テスト

Anthropic MPC inspector でテストするには、次を実行します。

'npx @modelcontextprotocol/inspector node ./dist/mcp-server.js'