Skip to main content
Glama
WorldPainter MCP

WorldPainter MCP

by ikunkk02-afk

WorldPainter MCP 0.3.0 — Windows 本地地形、植被与水域工具

通过 MCP 读取已保存的 .world 工程,生成润色计划、预览,再调用 WorldPainter 自带的 wpscript.exe 保存新副本。 它操作工程文件。要在 WorldPainter 窗口里看到修改,需要打开新副本;未保存的窗口状态无法读取。

安装与连接

环境:Windows、Python 3.11 或以上、WorldPainter。实际验证环境为 WorldPainter 2.27.1 / Java 22 / Python 3.14。 观众需要自行安装 WorldPainter 与 Python,压缩包包含本工具源码,不包含 WorldPainter、Python 或地图数据。

  1. 从 GitHub Releases 下载版本包,或使用仓库的 Code → Download ZIP 下载源码。解压到一个固定目录,例如 D:\Tools\worldpainter-mcp。

  2. 在该目录打开 PowerShell:

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install.ps1 -WPScript 'D:\WorldPainter\wpscript.exe'

将 wpscript.exe 的路径改为自己电脑上的实际路径。-Python 参数可以指定 Python 可执行文件,默认使用 Windows 的 py 启动器。 首次安装会联网下载 Python 依赖。后续读写地图通过本机 WorldPainter 进程执行。

  1. 在 MCP 客户端添加 STDIO 服务:

项目

示例

命令

D:\Tools\worldpainter-mcp\.venv\Scripts\python.exe

参数

-m worldpainter_mcp

工作目录

D:\Tools\worldpainter-mcp

环境变量

WPSCRIPT_PATH=D:\WorldPainter\wpscript.exe

工具超时

900 秒

Codex 与 Hermes 配置示例位于 examples/,请替换绝对路径。更新旧版本后重启 MCP 客户端,让 Python 服务重新加载。

Related MCP server: capcut-mcp

使用流程

先在 WorldPainter 保存工程,再交给助手:

请读取 D:\Maps\island.world,分析地形和海岸。按高度与坡度规划草地、裸岩、海岸以及 Minecraft 群系,创建草类植物图层。先生成预览,再把合理的方案另存为新的 .world 工程。

工具调用顺序:

  1. wp_get_world_info:核实文件、维度、范围和图层。

  2. wp_analyze_terrain:读取高度与坡度摘要。

  3. wp_plan_terrain_edit:生成计划,不保存地图。

  4. wp_preview_terrain_edit:生成高度前后对比、改变量与每项覆盖遮罩,返回 preview_id。

  5. 审阅预览后调用 wp_apply_terrain_plan:自动保存源文件快照,默认另存工程副本。

  6. 重新读取新副本,核实图层;在 WorldPainter 打开副本查看效果。

原文件、输入遮罩或编译后的覆盖数据在预览后变化,应用会被拒绝。默认最多处理一亿格点,8192×8192 地图约为 6711 万格点。

能力与参数

高度操作:平滑、局部抬高/降低、坡度限制、海岸柔化、山脊/谷地对比和侵蚀感处理。侵蚀感算法为视觉处理,不是水文模拟。 绘制操作:内置地表材质、已有图层数值、Minecraft 群系 ID、新建原生 Custom Plants 图层,以及按准备好的格点数据写入湖泊与河道床面、水位。 矩形、圆形、多边形可限定区域。灰度遮罩必须与整张维度同尺寸,左上角对应该维度最小坐标。 每项绘制可以单独指定 mask_path,它与全局遮罩相交。

植物示例,放入 paint_operations:

{
  "type": "plants",
  "layer": "Island | Low grass",
  "plants": [
    {"name": "Short Grass", "weight": 94},
    {"name": "Tall Grass", "weight": 4},
    {"name": "Dandelion", "weight": 2}
  ],
  "density": 0.30,
  "seed": 20261003,
  "mask_path": "D:\\Maps\\grass-mask.png"
}

density 为适宜区域中的覆盖比例,0~1;weight 为植物类型的相对权重。 植物使用 WorldPainter 的英文名称,图层名必须是新名字,避免替换已有图层配置。 覆盖位置由固定种子生成,原生 Plants 图层为开关型图层。植物只在有效基础方块上导出,不自动生成耕地。 草和花草采用 Minecraft 原生方块,本示例无需外部 schematic 资源。 BIT 图层通过开关接口绘制,数值型图层通过数值接口绘制。群系写入真实的 Biome 图层,和地表材质分别处理。

预览与检查

高度预览的 before/after/delta PNG 表示高度;纯地表或植物操作时,这三张图可以完全相同。 paint_summary 提供每项操作的覆盖格点数量和遮罩预览路径。助手可以叠加这些遮罩,制作彩色分区示意图。 这是规划与覆盖预览,不是 Minecraft 内的截图。实际植物方块在导出 Minecraft 地图时生成。

自检命令:

.\.venv\Scripts\python.exe -m worldpainter_mcp --doctor
.\.venv\Scripts\python.exe -m worldpainter_mcp --self-test
.\.venv\Scripts\python.exe tests\integration_vegetation.py

最后一项在本机创建 128×128 临时测试地图,通过真实 MCP 完成计划、预览、写入和读回,核实分区、植物、源文件不变,以及拒绝被篡改的预览。 测试记录保存在包目录下的 work/vegetation-test/。

验证边界

2026-10-03 在上述环境实际读取并写回 Vágar 8192×8192 工程;写入地表、五类群系与两组原生植物图层。 逐格对照确认高度与水位没有变化,植物覆盖没有落在海域或裸岩上。 这不是实测植被分类或物种调查。植物设置字段依赖 WorldPainter 2.27.1 的实现,升级 WorldPainter 后请先运行真实植物集成测试。 当前工具的重点是工程文件处理;不操控 WorldPainter 窗口,不附带商业树木素材,不自动检索地理水系数据,也不自动完成整张地图的 Minecraft 导出。

官方参考:

0.3.0 湖泊与河道水位

paint_operations 新增 {"type":"water","data_path":"D:\\Maps\\water-target.npz"}。 NPZ 使用 numpy 保存四个同长度一维数组:x、y 是绝对 WorldPainter 整数格点坐标;bed 是浮点床面高度;water 是整数水位。 数据不能包含重复坐标、非有限值或越界坐标。床面必须低于水位,且只能降低现有地面,不允许抬高地面。 水域数据会经过计划、预览、源文件校验、输入文件及编译数据哈希校验,再保存新副本。 预览的高度图包含床面变化;paint_summary 的水域遮罩显示水位操作范围。 要把植物从水域清除,另外添加 layer(layer=现有植物图层名,value=0,mask_path=水域遮罩);地表材质和群系同样分别绘制。

水位操作只接收准备好的格点数据。它不自行推测湖泊位置,不下载水系,不测量湖底深度,也不是水动力模拟。 请先对齐水域矢量与高程栅格,再制作床面和水位;河道宜保留地形落差并限制开挖深度。 将整张地图导出 Minecraft 后,仍需检查水流更新、瀑布、漏水及水岸观感。

水域真实集成测试:

.\.venv\Scripts\python.exe tests\integration_water.py

测试创建小型地图,经过真实 MCP 写入平水湖和阶梯河道,逐格验证保存值及区域外不变;应用缺失预览或被篡改编译文件时会拒绝写入。

开源许可

本工具采用 MIT License。WorldPainter 与 Python 需分别安装,遵循各自的许可;本仓库不分发它们或地图工程。

Available Tools

8 tools
wp_analyze_terrainC

Compute elevation and slope statistics, optional coast coverage, and a heightmap preview. Read-only.

Inputs: world_path (required), dimension, sea_level. Returns: object

wp_apply_terrain_planB

Apply an already previewed plan via WorldPainter, snapshot first, and save a new copy by default.

Inputs: plan_id (required), preview_id (required), output_path, overwrite_original, +1 more. Returns: object

wp_export_heightmapB

Export a dimension heightmap to PNG plus lossless bridge data. Dimension may be its selector, name or index.

Inputs: world_path (required), dimension, output_path. Returns: object

wp_get_world_infoB

Read a .world project name, platform, dimensions, bounds, height ranges and layer names. Read-only.

Inputs: world_path (required). Returns: object

wp_list_snapshotsB

List safety snapshots, optionally restricted to one original .world path.

Inputs: world_path. Returns: object

wp_plan_terrain_editA

Create a non-writing edit plan.

Height operation types: smooth(radius,passes,strength), erosion(iterations,talus,strength), ridge_valley(radius,scale,strength), raise_lower(delta,strength), slope_limit(max_slope,iterations,strength), coastline_soften(sea_level,width,radius,strength). Paint operation types: terrain(terrain), layer(layer,value), biome(biome_id), plants(layer, plants=[{name,weight}], density=0.25,seed=1), water(data_path): NPZ with equal 1D arrays x,y (absolute integer world coordinates), bed (float ground height), water (integer water level). Only lowers existing ground. Water does not clear plants or change terrain/biomes; add masked layer/terrain/biome operations. Plants creates a NEW native Custom Plants layer, with valid-block checks and no farmland. Each paint operation may have its own mask_path, intersected with the global mask. Use wp_get_world_info to see existing layer names; plants must use a new name. Region types: rectangle(x,y,width,height,feather), circle(center_x,center_y,radius,feather), or polygon(points,feather). mask_path may point to a grayscale image covering the full dimension. This tool never saves a .world file; preview is mandatory next.

Inputs: world_path (required), region, dimension, mask_path, +2 more. Returns: object

wp_preview_terrain_editA

Generate before/after/delta PNGs and a one-time preview_id for a plan. Does not write a .world file.

Inputs: plan_id (required). Returns: object

wp_rollback_snapshotB

Restore a snapshot to a new .world copy by default; original overwrite requires explicit opt-in.

Inputs: snapshot_id (required), output_path, overwrite_original. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct role in the terrain-editing workflow: inspection, export, analysis, planning, previewing, applying, and snapshot management. The plan/preview/apply trio is explicitly sequenced with non-overlapping outputs, so an agent can easily tell them apart.

    Naming Consistency5/5

    All tool names follow a consistent wp_ + verb_noun snake_case pattern (wp_get_world_info, wp_export_heightmap, wp_apply_terrain_plan, etc.). The compound nouns like terrain_edit and terrain_plan remain predictable and readable.

    Tool Count5/5

    Eight tools is well-scoped for a world-editing MCP with a plan-preview-apply safety pipeline and snapshot support. Each tool earns its place without redundancy or bloat.

    Completeness4/5

    The surface covers the core lifecycle: read world info, export/analyze terrain, plan/preview/apply edits, and list/rollback snapshots. Minor gaps exist, such as no tool to delete or prune snapshots, but agents can work around these limitations.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to author buildable QuadSpinner Gaea 2 .terrain projects, turn real DEM or synthetic elevation into Gaea-ready heightmaps and 16-bit erosion masks, have Gaea itself validate and build the project, and read back the exported heightmap and colour-map outputs. It bakes in the file-format, licence, schema-version and mask-bit-depth constraints that otherwise make Gaea-produced projects fail to open, build, or apply correctly.
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables reading and editing CapCut desktop draft projects, including adding/moving/trimming/splitting clips, text, audio, images, filters, transitions, masks, keyframe animation, audio fades, stickers, setting transforms, validation, and saving with backups.
      28
      MIT