Minecraft Server MCP

Instructions

Implementation Reference

• src/tools/config-tools.ts:132-212 (handler)

  Implementation of the 'setup_world' tool. This tool configures the server.properties file with world generation settings, requiring a server restart to take effect.

  server.tool(
    "setup_world",
    "Configure server.properties for generating a new world. Sets the level name, seed, world type, and other generation options. The server must be restarted (with the old world deleted or renamed) to generate the new world.",
    {
      level_name: z.string().describe("World folder name (e.g., 'world', 'creative_world')"),
      seed: z.string().optional().describe("World seed (blank for random)"),
      world_type: z
        .enum([
          "minecraft:normal",
          "minecraft:flat",
          "minecraft:large_biomes",
          "minecraft:amplified",
          "minecraft:single_biome_surface",
        ])
        .optional()
        .default("minecraft:normal")
        .describe("World generation type"),
      gamemode: z
        .enum(["survival", "creative", "adventure", "spectator"])
        .optional()
        .default("survival")
        .describe("Default game mode"),
      difficulty: z
        .enum(["peaceful", "easy", "normal", "hard"])
        .optional()
        .default("easy")
        .describe("Difficulty level"),
      hardcore: z.boolean().optional().default(false).describe("Enable hardcore mode"),
      generate_structures: z
        .boolean()
        .optional()
        .default(true)
        .describe("Generate villages, temples, etc."),
      generator_settings: z
        .string()
        .optional()
        .describe("JSON string for superflat/custom world generation settings"),
      spawn_protection: z
        .number()
        .optional()
        .default(16)
        .describe("Spawn protection radius in blocks"),
    },
    async (params) => {
      const properties: Record<string, string> = {
        "level-name": params.level_name,
        "level-type": params.world_type.replace(":", "\\:"),
        gamemode: params.gamemode,
        difficulty: params.difficulty,
        hardcore: String(params.hardcore),
        "generate-structures": String(params.generate_structures),
        "spawn-protection": String(params.spawn_protection),
      };
  
      if (params.seed !== undefined) {
        properties["level-seed"] = params.seed;
      }
      if (params.generator_settings !== undefined) {
        properties["generator-settings"] = params.generator_settings;
      }
  
      manager.properties.setMultiple(properties);
  
      const lines = [
        `World configuration set:`,
        `  Name: ${params.level_name}`,
        `  Seed: ${params.seed || "(random)"}`,
        `  Type: ${params.world_type}`,
        `  Gamemode: ${params.gamemode}`,
        `  Difficulty: ${params.difficulty}`,
        `  Hardcore: ${params.hardcore}`,
        `  Structures: ${params.generate_structures}`,
        ``,
        `To generate this world:`,
        `1. Stop the server if running`,
        `2. Delete or rename the existing world folder ("${params.level_name}") if it exists`,
        `3. Start the server - it will generate a new world with these settings`,
      ];
      return { content: [{ type: "text", text: lines.join("\n") }] };
    }
  );