Getting started

From sign-up to walking around your first AI-built world. Takes about five minutes, most of it waiting for your AI to finish the roof.

Quick start

Create an account. The free plan is enough to try everything.
Create an API key on your account page. It looks like mx_live_… and is shown once, so copy it somewhere safe.
Download the MCP, a single file called moxel-worlds-mcp.mjs. It needs Node.js 20 or newer, nothing else.
Register it with your AI using the commands below, then ask it to build something.
Open the app to watch it happen live.

The MCP is a small bridge: your AI runs it on your computer, and it forwards each tool call to your Moxel account with your key. Your maps live on our servers, not on your PC.

Install the MCP

Save moxel-worlds-mcp.mjs somewhere it can stay, for example C:\Tools\moxel\ or ~/tools/moxel/. Then pick your client:

Run this once in a terminal. Use your real key and the real path to the file.

terminal

claude mcp add moxel-worlds -e MOXEL_API_KEY=mx_live_xxx -- node C:\path\to\moxel-worlds-mcp.mjs

Add -s user after add to make it available in every project. Check it with claude mcp list: moxel-worlds should say connected.

Open Settings → Developer → Edit config in Claude Desktop, or edit the file directly:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server under mcpServers (merge it in if the file already has other servers), save, and restart Claude Desktop.

claude_desktop_config.json

{
  "mcpServers": {
    "moxel-worlds": {
      "command": "node",
      "args": ["<path>/moxel-worlds-mcp.mjs"],
      "env": { "MOXEL_API_KEY": "mx_live_..." }
    }
  }
}

On Windows, write the path with forward slashes (C:/Tools/moxel/moxel-worlds-mcp.mjs) or doubled backslashes.

Any client that speaks MCP over stdio works. Configure a server with:

Name	`moxel-worlds`
Transport	stdio
Command	`node`
Arguments	`/path/to/moxel-worlds-mcp.mjs`
Environment	`MOXEL_API_KEY=mx_live_…`

Treat your key like a password. Anyone with it can build in, and delete, your maps. If one leaks, revoke it on your account page and make a new one.

Your first build

Open the app in a browser tab, then ask your AI. Mentioning the tool by name helps the first time:

prompt

Use moxel-worlds to build a small Japanese tea house by a koi pond, render it at golden hour, and tell me when it's ready to export.

The AI creates a map, builds it piece by piece and takes renders to check its own work. The app follows along: an amber AI building light and an edit feed show what it's doing. You can fly around, edit by hand, or press G for the shader view while it works.

Example prompts

Be specific about size, style and mood. Ask for renders and the AI will look at its own work and fix things.

StructureA gothic cathedral, 60 blocks long, with flying buttresses, a rose window of stained glass and a crypt underneath.

IslandA floating island with a wizard tower, waterfalls pouring off the edges and roots hanging underneath. Render it at sunset.

Whole mapGenerate a 2000×2000 survival map: a mountain range in the north, a river to the sea in the south, and three villages linked by roads.

MinigameA 4-team bedwars map. Symmetric team islands with a bed and generator each, diamond islands between them, and an emerald centre.

InteriorFurnish the inside of the castle keep: a great hall with banners and a long table, a kitchen, and a library on the top floor.

RestyleMake the village look a hundred years older: mossy and cracked stone, broken fences, vines and overgrown paths.

LobbyA server hub on a cherry blossom island, with a central spire and one portal gate per game mode. Add a marker at each portal.

TerrainFlatten a site in the valley, build a fishing village on stilts over the lake, and plant a birch forest around it.

Pixel artA 64-block-tall statue of a knight holding a sword, standing on a plinth in the town square, lit with lanterns.

ExportAdd markers for spawn, the castle and the dungeon entrance, set spawn at the town gate, and export it as a world for 26.2.

Tool reference

What the AI can call. You don't need to know these to use Moxel Worlds, but naming one in a prompt can help. Every edit tool accepts preview: true to get an image back straight away.

Maps 7 tools

list_schematicsYour maps, their size and block count.

create_schematicStart a new, empty map, with any map features you want.

open_schematicSwitch to a map; the app follows.

rename_schematicRename it or set its description.

delete_schematicDelete a map (only when you ask).

schematic_infoSize, bounds, the bill of materials and the map's features.

set_featuresTurn map features on or off, like custom biomes.

Blocks 3 tools

search_blocksFind blocks by name or category.

block_infoEvery property, its valid values and defaults.

preview_blocksA labelled picture of up to 48 blocks.

Build 12 tools

place_blocksExact blocks at exact positions.

fillBoxes: solid, hollow, walls, outline, frame, floor, with a replace filter.

clearSet a box, or the whole map, to air.

sphere · cylinder · lineDomes, towers, beams, ropes and branches.

replace_blocksSwap one block for another, keeping facing and other states.

clone_regionCopy with rotation, mirroring and repeats.

run_scriptSandboxed JavaScript for loops, noise and procedural shapes.

undo · redoStep back through edits.

Architecture 6 tools

polygonExtrude any footprint: L-shaped houses, octagon towers, star plazas.

roofProper roofs over a wall footprint.

archRound, pointed or flat arches, with the wall built around them.

staircaseStraight or spiral stairs with correct facing, supports and railings.

treeNatural-looking trees of any species and size.

place_schematicStamp one of your maps into another, rotated or mirrored.

Terrain + biomes 13 tools

generate_terrainA whole landscape over a rectangle, up to 5000×5000 and beyond.

terrainGround under and around a build: hills, island, mountain, plateau.

carve_pathRoads, paths, rivers and canals that follow the land, with bridges.

flattenLevel a building site and blend it into the surroundings.

forestPlant mixed forests with undergrowth on natural ground.

scatterDecorate surfaces: flowers, grass, lanterns, vines.

paint_biomeRepaint the surface layer: podzol, snow, sand.

set_biome · list_biomesReal Minecraft biomes: colours, weather and mobs in game.

create_biome · edit_biome · delete_biomeYour own biomes: colours, sky, fog, particles and music (map feature).

render_mapA top-down map with hillshading, a grid and a scale bar.

See 4 tools

renderOverview sheets or 12 views incl. a perspective hero shot, with shaders, presets, cutaways and labels.

photoClose-up camera on a marker, point or box. Street-level views and 4-side orbits.

view_sliceOne layer as text, with a legend.

get_blocksRead exact blocks back.

Markers + files 6 tools

add_marker · list_markersNamed places, shown as pins in the app and renders.

list_references · view_referenceYour sketches and reference pictures: draw a plan in the app, and the AI sees it with world coordinates and a zone grid it can follow.

update_marker · remove_markerMove, rename or delete them.

export_schematicWorld, .schem, .litematic, .nbt or .mcfunction. Appears as a download.

import_schematicBring in .schem, .litematic or .nbt.

Materials

Anywhere a tool takes a block, it can take a material instead. This is how builds end up looking hand-made rather than flat. Results are the same every time for a given position; pass seed for a different roll.

Material	Example
Weighted mix	`"stone_bricks 70%, mossy_stone_bricks 20%, cracked_stone_bricks 10%"`
Gradient	`{"gradient": ["cobblestone", "stone_bricks", "polished_andesite"], "axis": "y"}`
Noise patches	`{"noise": ["grass_block", "moss_block", "coarse_dirt"], "scale": 6}`
Pattern	`{"pattern": "checker", "blocks": ["white_concrete", "black_concrete"]}`

Entries can nest, so a gradient of mixes works. You can make mixes by hand too: Shift+click blocks in the app's palette.

Map features

Features are optional extras for a map. They're all off unless you switch them on: in the app's New map dialog, later from the gear on a map (Map settings), or by asking your AI (create_schematic with features, or set_features). Right now there's one.

Custom biomes

Make biomes of your own, up to 32 per map. Each one is built on a vanilla biome, which supplies its weather, mobs, caves and anything you leave unset, and gets its own grass, foliage, water, sky and fog colours, floating particles (spore blossoms, ash, glowing spores, fireflies...), music and rain or snow. Your AI paints them like any other biome, and the app, renders and top-down maps show their colours straight away. Exported worlds carry them as a data pack, so the game shows them too. Try: "Turn on custom biomes, make a teal glowing mushroom grove with spore particles, and paint it around the lake."

Turning custom biomes off asks first: everywhere one is painted goes back to the vanilla biome it was built on. Schematic files (.schem, .litematic, .nbt) don't carry biomes, so custom biomes travel in world downloads only.

Export to Minecraft

As a playable world

Download the world. On your account page, pick the map's Download → World, or use Export in the app. You can also just ask the AI to export it.
Unzip it into your saves folder: %APPDATA%\.minecraft\saves on Windows, ~/Library/Application Support/minecraft/saves on macOS, ~/.minecraft/saves on Linux.
Open Minecraft Java 26.2 → Singleplayer, and pick the world. It's a creative, peaceful world with a void around the build.

Worlds are written for 26.2 by default, since a 26.3 save won't open in 26.2. Ask for version: "26.3" to get a 26.3 world. Blocks that only exist in 26.3 are swapped for the nearest 26.2 block, and the export lists each swap.

Custom biomes in game

A map with custom biomes gets them as a data pack inside the world, built for the version you exported (26.2 or 26.3). Check one with /execute if biome ~ ~ ~ moxel:your_biome, or press F3. /locate biome only finds the map's default biome, because the game looks those up from the world generator rather than from the painted map.

Markers in game

Every marker comes along as an in-game teleport. Each player gets a clickable list of places when they first join, and a marker set as spawn becomes the world spawn. A markers.txt with all coordinates is included too.

As a schematic

.schem (Sponge v3) for WorldEdit and FAWE: put it in your WorldEdit schematics folder, then //schem load name and //paste.
.litematic for Litematica: drop it in .minecraft/schematics and load it from the Litematica menu.
.nbt for structure blocks and .mcfunction for datapacks are available from the app's Export menu.

Schematic exports come with <file>.markers.txt, with marker coordinates relative to the schematic's origin.

Limits

	Free	Moxel Pro
Maps	3	500
Blocks per map	2 M	300 M
Storage	200 MB	20 GB
AI tool calls / day	150	No cap (up to 120 a minute)

Your live usage is on your account page. See pricing.

Troubleshooting

My AI doesn't see the moxel-worlds tools

Restart the client after adding the server. In Claude Code, claude mcp list shows whether it connected. Check the path to the .mjs file is right and absolute.

"node" is not recognized

Install Node.js 20 or newer, then open a new terminal so it's on your PATH.

401 / invalid API key

The key was mistyped, revoked, or from another account. Create a new one on your account page and update your config.

The app doesn't show what the AI is building

Make sure you're logged into the same account the key belongs to. The app follows whichever map the AI opened last; pick it from the map list if you've switched.

"Daily limit reached"

Free accounts get 150 AI tool calls a day, and the count resets daily. Moxel Pro removes the cap.

Still stuck? Ask in the Moxel Discord. The #help forum is the quickest way to get an answer, and you'll find other people's builds and prompts there too.