Minecraft MCP Server

Instructions

Implementation Reference

• src/bot.ts:507-526 (handler)

  Handler function that implements the 'find-entity' tool logic: filters entities by type, finds the nearest one within maxDistance using bot.nearestEntity, and returns its position.

  async ({ type = '', maxDistance = 16 }): Promise<McpResponse> => {
    try {
      const entityFilter = (entity: any) => {
        if (!type) return true;
        if (type === 'player') return entity.type === 'player';
        if (type === 'mob') return entity.type === 'mob';
        return entity.name && entity.name.includes(type.toLowerCase());
      };
  
      const entity = bot.nearestEntity(entityFilter);
  
      if (!entity || bot.entity.position.distanceTo(entity.position) > maxDistance) {
        return createResponse(`No ${type || 'entity'} found within ${maxDistance} blocks`);
      }
  
      return createResponse(`Found ${entity.name || (entity as any).username || entity.type} at position (${Math.floor(entity.position.x)}, ${Math.floor(entity.position.y)}, ${Math.floor(entity.position.z)})`);
    } catch (error) {
      return createErrorResponse(error as Error);
    }
  }

• src/bot.ts:503-506 (schema)

  Input schema for the 'find-entity' tool using Zod: optional type (string) and maxDistance (number).

  {
    type: z.string().optional().describe("Type of entity to find (empty for any entity)"),
    maxDistance: z.number().optional().describe("Maximum search distance (default: 16)")
  },

• src/bot.ts:499-528 (registration)

  Registration of the 'find-entity' tool via server.tool() inside the registerEntityTools function.

  function registerEntityTools(server: McpServer, bot: any) {
    server.tool(
      "find-entity",
      "Find the nearest entity of a specific type",
      {
        type: z.string().optional().describe("Type of entity to find (empty for any entity)"),
        maxDistance: z.number().optional().describe("Maximum search distance (default: 16)")
      },
      async ({ type = '', maxDistance = 16 }): Promise<McpResponse> => {
        try {
          const entityFilter = (entity: any) => {
            if (!type) return true;
            if (type === 'player') return entity.type === 'player';
            if (type === 'mob') return entity.type === 'mob';
            return entity.name && entity.name.includes(type.toLowerCase());
          };
  
          const entity = bot.nearestEntity(entityFilter);
  
          if (!entity || bot.entity.position.distanceTo(entity.position) > maxDistance) {
            return createResponse(`No ${type || 'entity'} found within ${maxDistance} blocks`);
          }
  
          return createResponse(`Found ${entity.name || (entity as any).username || entity.type} at position (${Math.floor(entity.position.x)}, ${Math.floor(entity.position.y)}, ${Math.floor(entity.position.z)})`);
        } catch (error) {
          return createErrorResponse(error as Error);
        }
      }
    );
  }