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"] } },