Minecraft MCP Server

Instructions

Implementation Reference

• mcp-server/src/mcp-server.ts:142-247 (handler)

  The main execution logic for the 'joinGame' tool. Creates a mineflayer bot instance, loads plugins (pathfinder, pvp, tool, collectblock), configures logging and properties, waits for the bot to spawn, and registers it with the BotManager.

  if (name === "joinGame") {
      try {
          const { username, host, port } = args as { username: string; host?: string; port?: number };
  
          // Use provided values, fall back to command line options, then defaults
          const serverHost = host || options.host || 'localhost';
          const serverPort = port || (options.port ? parseInt(options.port) : 25565);
  
          console.error(`[MCP] Attempting to spawn bot '${username}' on ${serverHost}:${serverPort}`);
  
          // Create a new bot
          const bot = mineflayerCreateBot({
              host: serverHost,
              port: serverPort,
              username: username
              // Auto-detect version by not specifying it
          }) as any; // Type assertion to allow adding custom properties
  
          // Dynamically import and load plugins
          const [pathfinderModule, pvpModule, toolModule, collectBlockModule] = await Promise.all([
              import('mineflayer-pathfinder'),
              import('mineflayer-pvp'),
              import('mineflayer-tool'),
              import('mineflayer-collectblock')
          ]);
  
          // Load plugins
          bot.loadPlugin(pathfinderModule.pathfinder);
          bot.loadPlugin(pvpModule.plugin);
          bot.loadPlugin(toolModule.plugin);
          bot.loadPlugin(collectBlockModule.plugin);
  
          // Add Movements constructor to bot for skills that create movement configurations
          bot.Movements = pathfinderModule.Movements;
  
          // Add a logger to the bot
          bot.logger = {
              info: (message: string) => {
                  const timestamp = new Date().toISOString();
                  console.error(`[${username}] ${timestamp} : ${message}`);
              },
              error: (message: string) => {
                  const timestamp = new Date().toISOString();
                  console.error(`[${username}] ${timestamp} : ERROR: ${message}`);
              },
              warn: (message: string) => {
                  const timestamp = new Date().toISOString();
                  console.error(`[${username}] ${timestamp} : WARN: ${message}`);
              },
              debug: (message: string) => {
                  const timestamp = new Date().toISOString();
                  console.error(`[${username}] ${timestamp} : DEBUG: ${message}`);
              }
          };
  
          // Register the bot
          const botId = botManager.addBot(username, bot);
  
          // Wait for spawn
          await Promise.race([
              new Promise<void>((resolve, reject) => {
                  bot.once('spawn', () => {
                      console.error(`[MCP] Bot ${username} spawned, initializing additional properties...`);
  
                      // Initialize properties that skills expect
                      bot.exploreChunkSize = 16; // INTERNAL_MAP_CHUNK_SIZE
                      bot.knownChunks = bot.knownChunks || {};
                      bot.currentSkillCode = '';
                      bot.currentSkillData = {};
  
                      // Set constants that skills use
                      bot.nearbyBlockXZRange = 20; // NEARBY_BLOCK_XZ_RANGE
                      bot.nearbyBlockYRange = 10; // NEARBY_BLOCK_Y_RANGE
                      bot.nearbyPlayerRadius = 10; // NEARBY_PLAYER_RADIUS
                      bot.hearingRadius = 30; // HEARING_RADIUS
                      bot.nearbyEntityRadius = 10; // NEARBY_ENTITY_RADIUS
  
                      // Initialize chat history tracking
                      initializeChatHistory(bot);
  
                      resolve();
                  });
                  bot.once('error', (err: Error) => reject(err));
                  bot.once('kicked', (reason: string) => reject(new Error(`Bot kicked: ${reason}`)));
              }),
              new Promise<never>((_, reject) =>
                  setTimeout(() => reject(new Error('Bot spawn timed out after 30 seconds')), 30000)
              )
          ]);
  
          return {
              content: [{
                  type: "text",
                  text: `Bot '${username}' successfully joined the game on ${serverHost}:${serverPort}. Bot ID: ${botId}`
              }]
          };
      } catch (error) {
          return {
              content: [{
                  type: "text",
                  text: `Failed to join game: ${error instanceof Error ? error.message : String(error)}`
              }],
              isError: true
          };
      }
  }

• mcp-server/src/mcp-server.ts:89-106 (schema)

  The input schema definition for the 'joinGame' tool, specifying parameters for username (required), host, and port.

  inputSchema: {
      type: "object",
      properties: {
          username: {
              type: "string",
              description: "The username for the bot"
          },
          host: {
              type: "string",
              description: "Minecraft server host (defaults to 'localhost' or command line option)"
          },
          port: {
              type: "number",
              description: "Minecraft server port (defaults to 25565 or command line option)"
          }
      },
      required: ["username"]
  }

• mcp-server/src/mcp-server.ts:86-107 (registration)

  Registration of the 'joinGame' tool in the ListToolsRequestSchema handler, defining its name, description, and input schema for discovery.

  {
      name: "joinGame",
      description: "Spawn a bot into the Minecraft game",
      inputSchema: {
          type: "object",
          properties: {
              username: {
                  type: "string",
                  description: "The username for the bot"
              },
              host: {
                  type: "string",
                  description: "Minecraft server host (defaults to 'localhost' or command line option)"
              },
              port: {
                  type: "number",
                  description: "Minecraft server port (defaults to 25565 or command line option)"
              }
          },
          required: ["username"]
      }
  },