mc-ai-connection
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Ask for "a stone-brick tower next to Steve" or "a glass dome of radius 10 at the origin", and the AI turns it into server commands.
Highlights
Shapes:
fill, sphere, cylinder, line, pyramid, arch, spiral stairs, roof, and walls with windows. Large areas are split automatically to stay under the/filllimit of 32768 blocks.Palettes: mix blocks by ratio with a
seed, so a dry run and the real run match.Schematics and copy: paste
.schem(Sponge v2/v3) and structure.nbtfiles, and copy regions with rotation and flips.Undo:
set_block,fill, andbuild_*are backed up first and can be undone, newest first.Dry run: shows the command count, the most blocks that could change, and the bounding box before anything runs.
Version checks: with a
version, block names, renames, and build height are checked before writing.Multiple servers, optionally through an SSH tunnel.
Command policy and an operation log: dangerous commands such as
stop,op, andbanare refused by default.
What is verified
The unit tests (pnpm test) run against a fake world, with no server.
The author has run it on one real setup only: a Paper server on Minecraft 26.3, including a cathedral of about 700 commands. Other server software and versions are not verified. Client-side actions such as camera, movement, and screenshots are out of scope.
Related MCP server: MCP Minecraft Remote
Quick start
You need Bun, pnpm, and a Minecraft Java server with RCON enabled.
1. Install
git clone https://github.com/Lapius7/mcp-minecraft-controller
cd mcp-minecraft-controller
pnpm install2. Enable RCON in server.properties, then restart the server.
enable-rcon=true
rcon.port=25575
rcon.password=use-a-long-random-password3. Register it with your AI client. For Claude Code, run:
claude mcp add mc \
-e MC_RCON_PASSWORD=use-a-long-random-password \
-- bun run /absolute/path/to/mcp-minecraft-controller/src/index.tsFor Codex, add this to ~/.codex/config.toml:
[mcp_servers.mc]
command = "bun"
args = ["run", "/absolute/path/to/mcp-minecraft-controller/src/index.ts"]
env = { MC_RCON_PASSWORD = "use-a-long-random-password" }Any other MCP client works if it can launch bun run src/index.ts over stdio.
4. Try it. Start the server and ask the AI: "List the online players" or "Where is Steve standing?".
Tools
Tool | Description |
| List the registered servers and the current default |
| Change the default server |
| Run one command and return its output. A leading |
| Run up to 2000 commands in order |
| Get a player's position, rotation, and dimension |
| Place one block |
| Fill a box. |
| Build a sphere (radius 1 to 60), optionally hollow |
| Build a cylinder (radius 1 to 60, height 1 to 320), optionally hollow |
| Draw a 3D line between two points |
| Square pyramid (optionally hollow) |
| Semicircular arch with legs, thickness and depth |
| Spiral stairs around an optional center pillar (one block up per step) |
| Gable or hip roof; |
| Copy a region to another place with 90° rotation and x/z flips (server-side |
| Paste a |
| Four walls with evenly spaced windows and a door opening (air; no door block) |
| Undo the latest writes ( |
| List the writes |
| Show the latest log entries (runs, dry runs, refusals, failures, undos) |
| Count blocks by type in a region (read only) |
set_block, fill, and build_* take dryRun: true, which runs nothing and returns the command count, the most blocks that could change, and the bounding box.
Run a large build withdryRun: true first to check its size and bounding box before anything is written.
Coordinates are absolute integers in the form [x, y, z]. Blocks accept block states, such as oak_stairs[facing=north]. Shape tools return a short summary (commands run, succeeded, sample failures) instead of dumping every response.
run_command can run any command the server console can, so the AI can also change the time, weather, game rules, and entities, give items, and teleport players.
How an AI builds
It calls
get_player_posto find a base coordinate.It picks shapes (
fill,build_sphere, ...) and, for fine detail, sends many commands throughrun_commands.It checks results with commands such as
execute if block x y z <block>, which return "Test passed" or "Test failed".
Multiple servers
Register several servers in ~/.config/mc-ai-connection/servers.json (override the path with MC_SERVERS_FILE). See servers.example.json. Keep the file private (chmod 600).
Field | Description |
| RCON address. With |
| The password, or the name of an environment variable that holds it |
| Optional. An SSH host from |
| Optional. The Minecraft version (for example |
| Free text shown by |
| The server used when a call has no |
Every tool takes an optional server argument. list_servers shows what is registered, and use_server changes the default until the MCP restarts. Without the file, the MC_RCON_* variables below define a single server named default, as before. With the file, they are ignored.
Environment variables
Variable | Default | Description |
|
| Server host |
|
| RCON port |
| empty | RCON password |
|
| Maximum number of blocks one operation may change |
|
| Maximum number of blocks one operation may mix with a palette |
|
| Maximum number of columns that |
Settings file
Behavior settings live in ~/.config/mc-ai-connection/config.json (override the path with MC_CONFIG_FILE). See config.example.json. Every field is optional.
The directory is still namedmc-ai-connection, after the project's old name. It is kept so that existing settings keep working.
Field | Default | Description |
|
| Commands that are refused. Matched by prefix on words, so |
|
| If not empty, only commands matching an entry run. |
|
| Write the operation log |
|
| Where the log goes |
|
| Save original blocks before each write so it can be undone |
|
| History entries kept per server. Older ones are dropped |
|
|
|
|
| Largest number of blocks one operation may back up |
The lists apply to the commands you or the AI ask for: run_command, run_commands, and the ones that fill and build_* generate, including the command after run in execute ... run <command>. The MCP's own internal commands (the clone and forceload that undo and inspect_region use, and the data get behind get_player_pos) are not checked, so a deny rule on clone does not break undo. The history lives in MC_STATE_DIR (default ~/.local/state/mc-ai-connection).
Versions
When a server has a version, the write tools (set_block, fill, build_*, copy_region, paste_schematic) check the commands before anything is written, and the dry run shows the same result:
Block names: a name that does not exist in that version is rejected with a "did you mean" hint. The lists come from minecraft-data for 1.16.5 through 26.1 (
bun scripts/gen-blocks.tsregeneratessrc/blocks.data.ts). For a version between two listed ones (such as 1.21.2), a name is accepted if either neighbor has it. Versions older or newer than the list are not checked (a note says so). Names from other namespaces and#tagsare not checked.Renamed blocks are translated to the name that version uses:
grass_path/dirt_path(1.17),grass/short_grass(1.20.3),chain/iron_chain(1.21.9). This works in both directions.Height: 0 to 255 before 1.18, -64 to 319 from 1.18.
run_command and run_commands are not translated; their command text is sent as written. Without a version, nothing is checked. The version is not detected from the server, because RCON has no vanilla command for it.
Block palettes
Where a tool takes block (set_block, fill, build_sphere, build_cylinder, build_line), you can pass a list instead of one name to mix blocks by ratio:
{ "block": [{ "block": "stone_bricks", "weight": 70 }, { "block": "mossy_stone_bricks", "weight": 30 }], "seed": 1 }weight is relative (it need not add up to 100). The same seed gives the same pattern, so a dry run and the real run match. A palette places blocks one by one (runs of the same block are merged into one fill), so it is capped by MC_MAX_PALETTE_BLOCKS. With fill, mode can be replace, hollow, or outline.
Progress
For long operations (the write tools and run_commands), the server sends MCP notifications/progress while commands run, roughly every 5% or every second. A client only gets them if it sends a progressToken with the call; clients that do not are unaffected. The count is commands run, not blocks. The backup step before a write does not report progress.
Operation log
Every call that runs or refuses commands is appended to operations.jsonl (one JSON object per line: time, server, tool, status, summary, command counts). By default it sits next to the undo history in MC_STATE_DIR, and each entry carries the history ID (historyId), so you can match a log line to an undo entry. The file is rotated to operations.jsonl.1 at 5 MB.
Undo
Before set_block, fill, and build_* write, the MCP copies the region to a backup area with /clone, so block states and block entities such as chest contents come back exactly. The backup area is far from the spawn (undo.origin) and its chunks are force-loaded only while an entry is kept. undo copies it back and clears the backup.
History is per server and per operation. Entries can only be undone newest first, because restoring an old one under a newer overlapping build would corrupt the world.
If the backup fails, nothing is written. If the restore fails, the entry is kept so you can retry.
The region must be loaded, because
/cloneneeds loaded chunks. Everything runs in the dimension RCON commands use (the overworld).run_commandandrun_commandsare not covered. The MCP cannot know what an arbitrary command changes. Build the part you may want back withfillorbuild_*.Entities (mobs, dropped items) are not saved.
Troubleshooting
Failed to connect
The server is not running, or RCON is not enabled. Check that
enable-rcon=trueis set and the server was restarted.The host is wrong. If the server runs on Windows and the AI runs in WSL2,
127.0.0.1may not reach it. Use the Windows host IP (the default gateway shown byip route show default) asMC_RCON_HOST, or switch WSL to mirrored networking (networkingMode=mirroredin.wslconfig).
Command syntax errors
Command syntax changes between Minecraft versions. For example, in 26.x time query daytime no longer exists and you use time query day. Let the AI read the error and retry, or ask it to check the command with run_command first.
Safety
RCON is unencrypted and has full control of the server. Never expose the RCON port to the internet. Use a strong password and a firewall.
stop, op, ban, and similar commands are refused by default (see the settings file). Only connect to servers you own, and tighten commands.allow if the AI should do less.
undo covers set_block, fill, and build_* only. Back up the world before large builds, and before anything done through run_command. MC_MAX_VOLUME refuses oversized single operations.
Only server-side commands are available. Client-side actions such as camera, movement, and screenshots are out of scope.
Development
pnpm check # type check and unit tests (no server needed)
pnpm test # unit tests only
pnpm start # start the MCP server on stdioFile | Role |
| Minimal RCON client |
| Server registry, config file, SSH tunnels |
| Pure functions that turn shapes into command lists |
| Command allow list and deny list |
| Works out which blocks a command list changes |
| Backup before writing, and undo |
| Shared flow for writes: policy, dry run, backup, run |
| Mix blocks by ratio |
| Copy/paste with rotation and flips as |
| Read |
| Per-version block names, renames and height checks |
| Pyramid, arch, spiral stairs, roof, walls with windows |
| Operation log file |
| Block counts for a region |
| Settings file |
| MCP tool definitions |
Roadmap
Translate command syntax differences for
run_command(the write tools already handle block names, renames and heights)A companion MCP that reports a user's installed mods
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Manage NodePal Minecraft servers, worlds, mods, backups and console from AI agents.
Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Hosted MCP server to manage a restaurant menu from AI agents - 39 tools over the DuckHub API.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI interactions with a running Minecraft server inside a Docker container using RCON, allowing models to programmatically create Minecraft builds and manage the server.10-
- AlicenseCqualityDmaintenanceAllows AI assistants to connect to and control Minecraft players on remote servers, enabling navigation, building, mining, inventory management, entity interaction, and chat communication through natural language commands.2711 npm13MIT
- FlicenseNot gradedqualityDmaintenanceEnables control of a Minecraft server through RCON commands via natural language, including game commands, chat-based AI interactions, and server management capabilities.6-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to connect to Minecraft servers as a bot, allowing cooperative building, movement, combat, and chat in the same world.4 npm1Apache 2.0