MC-World-MCP

Offline-only MCP tools for operating on a Minecraft server directory.

This MCP intentionally does not use RCON, sockets, online player queries, or server start/stop controls. It only reads and writes local files such as level.dat, datapacks, structure templates, logs, and Anvil region files.

The complete write path targets Java Edition / Arclight 1.20.1 and 1.21.1 worlds with DataVersion 3465 or 3955. Other Java Anvil worlds are detected and exposed for best-effort reads, but world writes are rejected unless the version adapter marks them as fully supported. Bedrock LevelDB worlds are detected as unsupported.

Run

When this project lives at E:/VC/mc-world-mcp and a server workspace lives two levels below E:/VC, the workspace .vscode/mcp.json starts the server with:

{
  "command": "python",
  "args": ["-m", "mc_world_mcp.server"],
  "env": {
    "PYTHONPATH": "${workspaceFolder}/../mc-world-mcp/src",
    "MC_SERVER_ROOT": "${workspaceFolder}"
  }
}

MC_SERVER_ROOT may point at either the Arclight server root that contains server.properties and world/, or at a workspace/modpack root that contains a server/ subdirectory. Assistants can also call discover_server_roots() and select_server_root() to choose the active server root at runtime.

World selection follows server.properties level-name, so a server using level-name=world_regen_source is operated through that directory rather than a hardcoded world/. Set MC_WORLD_NAME to override this explicitly.

Safety

All write tools:

• reject paths outside MC_SERVER_ROOT

• reject writes when a server or unknown java/javaw process is running; recognized Minecraft client Java processes are ignored

• reject Java world writes unless the selected world is DataVersion 3465 or 3955

• back up every modified file under backup/mc_world_mcp/<timestamp>/

• write a manifest.json describing the changed files

Read tools are allowed while the server is running.

Tool Groups

• Server/files: summaries, safe file read/write, logs, version/platform detection

• Source worlds: local world inventory, server-generation workflow guidance, source/target chunk comparison, and offline chunk import

• NBT: level.dat, player data, world data, structure NBT

• Datapacks: folder and zip datapack listing, validation, search, read, write

• Worldgen: datapack/mod/plugin interface listing, resource checks, source-world simulation, and report summaries

• Regions: scan, inspect chunks, get/read/set/fill/replace blocks, block state strings

• World diagnostics: dimensions, world coverage, chunk palettes, log issue grouping

• World data: block entities, external entity regions, POI regions, biome boxes, heightmap clearing, chunk pruning

• Templates: list/read/write .nbt structure templates, export/place blocks with block entities and best-effort entities

• Preview: offline PNG map, slice, and structure-template previews under backup/mc_world_mcp/previews/

• Safety: offline checks, backup listing, backup restore

Optional Preview Acceleration

Preview rendering and source-world generation simulation have pure-Python fallbacks and can optionally use a compiled Cython module for hot loops such as block-state index decoding, chunk surface projection, close-up side sampling, source-world floor projection, structure-template projection, and item-NBT multi-view recomputation.

On Windows, compile the extension in place:

python setup.py build_ext --inplace

The source distribution includes generated C code, so Cython is optional for normal builds. Install mc-world-mcp[preview-accel] or python -m pip install Cython only when you want to regenerate the C file from _preview_accel.pyx. For wheel builds, set MC_WORLD_MCP_BUILD_ACCEL=1 to opt in to compiling the extension.

This creates a platform-specific mc_world_mcp._preview_accel.pyd next to the Python sources. If the compiled module is present, preview and simulation tools load it automatically; otherwise they continue using the pure-Python implementation. Building the .pyd requires the Microsoft C++ Build Tools matching the active Python version.

The repository may include a prebuilt src/mc_world_mcp/_preview_accel.cp311-win_amd64.pyd for Windows x64 CPython 3.11. Other Python versions, platforms, or architectures should rebuild the extension locally.

Assistant MCP Instructions

AI assistants working on this Minecraft workspace should use MCP tools in this order:

1. Read MCP-provided instructions.

   • The mc-world server exposes this guidance in its server instructions.

   • Call assistant_instructions() first when tool choice or workflow is unclear.

   • MCP clients that support resources can read mc-world://assistant-instructions.

   • MCP clients that support prompts can use mc_world_assistant_instructions.

2. Read project context first.

   • Read Copilot repo memory when available, especially project overview, datapacks, tool reference, gotchas, change history, and MCP server notes.

   • Then read local files such as README.md, .github/copilot-instructions.md, server.properties, datapack files, and logs as needed.

3. Use minecode for Minecraft reference lookups.

   • Command syntax: call get_wiki_command_info, then spyglass_get_commands when exact version syntax matters.

   • IDs and registries: call spyglass_get_registries for blocks, items, entities, biomes, enchantments, and other registries.

   • Vanilla JSON: call Misode tools such as misode_get_preset_data, misode_get_presets, misode_get_loot_tables, and misode_get_recipes.

   • Wiki background: call search_wiki, then get_wiki_page_content.

4. Use mc-world for local server and world operations.

   • Start with server_summary(), discover_server_roots() / select_server_root() when the root is wrong, detect_world_version(), world_summary(), and check_offline_safety().

   • For datapacks, use list_datapacks(), validate_datapacks(), search_datapack_files(), read_datapack_file(), and write_datapack_file().

   • For worldgen diagnosis, use list_generation_interfaces(), worldgen_report(), list_worldgen_resources(), and validate_worldgen_references().

   • For logs, use analyze_latest_log(), read_server_log(), and grep_server_log().

   • For Anvil data, use scan_regions(), scan_world_coverage(), inspect_chunk(), summarize_chunk_palette(), get_block(), read_block_box(), set_block(), fill_blocks(), and replace_blocks().

   • For NBT edits, use read_level_dat(), write_level_dat_value(), read_nbt_file(), write_nbt_value(), and write_chunk_nbt_value().

   • For entities, block entities, POI, biomes, and heightmaps, use list_entities(), add_entity(), edit_entity(), delete_entities(), add_block_entity(), edit_block_entity(), list_poi(), delete_poi(), set_biome_box(), and refresh_heightmaps().

   • For structures, use list_structure_templates(), read_structure_template(), write_structure_template(), write_structure_template_value(), export_region_to_template(), and place_template_to_region().

   • For previews, use render_map_preview(), render_closeup_map_preview(), render_slice_preview(), render_template_preview(), and render_item_nbt_preview().

   • For backups, use create_backup(), list_backups(), and restore_backup_manifest().

5. Respect the mc-world safety boundary.

   • Do not use RCON, sockets, online player queries, or server start/stop controls.

   • Read tools may run while the server is online.

   • Write tools require the server to be offline and will reject writes while server or unknown java/javaw processes are running. Recognized Minecraft client Java processes are ignored.

   • World writes are supported only for Java Anvil DataVersion 3465 or 3955.

   • Every write creates a backup under backup/mc_world_mcp/<timestamp>/ with manifest.json.

6. Use source worlds for real datapack, mod, or plugin worldgen.

   • mc-world does not execute biome modifiers, jigsaw placement, datapack worldgen, mod worldgen, or plugin worldgen.

   • list_generation_interfaces() exposes the open datapack, mod jar, and plugin jar generation inputs visible to the server.

   • Generate chunks in Minecraft/Arclight first, then stop the server.

   • Select the target world with MC_WORLD_NAME, for example MC_WORLD_NAME=world.

   • Use worldgen_source_plan("world_regen_source"), list_local_worlds(), simulate_worldgen_generation(...), and compare_world_chunks(...) before importing.

   • Use import_chunks_from_world("world_regen_source", chunks, confirm=true) only after confirming the source and target are different worlds.

7. Recommended diagnosis workflows.

   • Datapack load issue: validate_datapacks() -> worldgen_report() -> analyze_latest_log() -> search_datapack_files() -> read_datapack_file().

   • Structure generation issue: list_generation_interfaces() -> worldgen_report() -> list_worldgen_resources(type="worldgen/structure") -> validate_worldgen_references() -> simulate_worldgen_generation(...) -> read_level_dat("Data.WorldGenSettings") -> grep_server_log("structure").

   • Map visual check: scan_world_coverage() -> render_map_preview(..., "top") -> render_map_preview(..., "ocean_floor") -> inspect_chunk() or summarize_chunk_palette().

   • Offline edit: check_offline_safety() -> create or rely on automatic backup -> perform one focused write -> render or inspect the affected area.

Current Server Workflow

For the current Arclight server workspace, server.properties controls the active world through level-name. With the README MCP config above, all world tools automatically target that active world instead of a hardcoded world/.

This MCP still does not execute Minecraft worldgen. Datapack biome modifiers, jigsaw structures, mod structures, plugin-provided generation, coral placement, and sand dunes must be generated by Minecraft/Arclight in a source world first. The MCP can then inspect that generated source world offline, simulate the result from the generated files, and copy selected generated chunks into the active target world.

For import work, launch the MCP with the target world selected, for example MC_WORLD_NAME=world, and pass the generated source world as source_world_name="world_regen_source". The source and target worlds must be different local directories.

Useful checks:

• worldgen_report() summarizes datapacks, worldgen resources, validation findings, and log-derived resource issues.

• list_generation_interfaces() summarizes datapack resources plus mod/plugin jar generation interfaces and metadata.

• validate_worldgen_references() finds common missing same-namespace worldgen and structure references.

• list_local_worlds() lists source and target world directories under the server root.

• worldgen_source_plan("world_regen_source") explains the safe source-world generation/import workflow.

• simulate_worldgen_generation("world_regen_source", min_cx, min_cz, max_cx, max_cz) treats server-generated source chunks as a simulation sample, returns success/completeness signals, Cython acceleration status, block/height summaries, and preview PNG paths.

• compare_world_chunks("world_regen_source", min_cx, min_cz, max_cx, max_cz) shows which generated source chunks exist and which target chunks would be overwritten.

• import_chunks_from_world("world_regen_source", [{"cx": 0, "cz": 0}], confirm=true) copies terrain, entity, and POI chunk records from an already-generated source world into the active world.

• write_chunk_nbt_value(cx, cz, path, snbt_value) edits one chunk NBT path while offline.

• add_block_entity(x, y, z, block_state, block_entity_snbt) places a block and writes its block entity NBT.

• add_entity(entity_snbt) appends an entity to an existing external entity chunk selected by its Pos.

Offline visual checks:

• render_map_preview(x1, z1, x2, z2, "surface") renders a top-down PNG. y_mode also accepts top, ocean_floor, seafloor, or an integer Y level such as "26". Previews can render up to 1,048,576 output pixels; pass sample=2 or higher for faster downsampled overviews of larger areas.

• render_closeup_map_preview(x1, z1, x2, z2, "surface", view="oblique", side_depth=32) renders a close-up pseudo-3D terrain PNG from real Anvil columns, including visible top faces, height differences, and side faces. Views include oblique, south_east, south_west, north_west, and north_east; side faces sample real blocks below each top face up to side_depth layers instead of extending the top block through the whole column. The result reports whether Cython accelerated the close-up recomputation.

• render_slice_preview("x", fixed, min_z, max_z, min_y, max_y) renders a vertical slice.

• render_template_preview(template_path) renders a structure .nbt projection.

• render_item_nbt_preview(item_snbt, views=["front", "oblique"]) renders an item stack SNBT/NBT preview from local resource-pack, mod, plugin, or datapack assets. Views include front, back, left, right, top, bottom, isometric, and oblique; the result reports whether Cython accelerated the view recomputation.

Preview tools are read-only against the world data and write PNG files under backup/mc_world_mcp/previews/<timestamp>/.