Skip to main content
Glama
mc-ai-connection

mc-ai-connection

by Lapius7
README.md
# mc-ai-connection

[日本語](README.ja.md)

An MCP server that lets AI assistants (Claude, Codex, and any other MCP client) build and operate on a Minecraft Java server. It talks to the server over RCON, so no mod is required.

```
AI client ──MCP (stdio)──▶ mc-ai-connection ──RCON──▶ Minecraft server
```

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 commands. It has been tried on a Paper server running Minecraft 26.3, including a full cathedral build of about 700 commands.

## Requirements

- [Bun](https://bun.sh) and [pnpm](https://pnpm.io)
- A Minecraft Java server with RCON enabled

## Setup

### 1. Install

```sh
git clone https://github.com/Lapius7/mc-ai-connection
cd mc-ai-connection
pnpm install
```

### 2. Enable RCON on the server

Add this to `server.properties` and restart the server.

```properties
enable-rcon=true
rcon.port=25575
rcon.password=use-a-long-random-password
```

### 3. Register it with your AI client

Claude Code:

```sh
claude mcp add mc \
  -e MC_RCON_PASSWORD=use-a-long-random-password \
  -- bun run /absolute/path/to/mc-ai-connection/src/index.ts
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.mc]
command = "bun"
args = ["run", "/absolute/path/to/mc-ai-connection/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, then ask the AI: "List the online players" or "Where is Steve standing?".

## Configuration

| Variable | Default | Description |
|---|---|---|
| `MC_RCON_HOST` | `127.0.0.1` | Server host |
| `MC_RCON_PORT` | `25575` | RCON port |
| `MC_RCON_PASSWORD` | empty | RCON password |
| `MC_MAX_VOLUME` | `200000` | Maximum number of blocks one operation may change |

## Tools

| Tool | Description |
|---|---|
| `run_command` | Run one command and return its output. A leading `/` is optional |
| `run_commands` | Run up to 2000 commands in order |
| `get_player_pos` | Get a player's position, rotation, and dimension |
| `set_block` | Place one block |
| `fill` | Fill a box. `mode` is `replace`, `hollow`, `outline`, `keep`, or `destroy`. Large boxes are split automatically to stay under the 32768-block limit |
| `build_sphere` | Build a sphere (radius 1 to 60), optionally hollow |
| `build_cylinder` | Build a cylinder (radius 1 to 60, height 1 to 320), optionally hollow |
| `build_line` | Draw a 3D line between two points |

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

1. It calls `get_player_pos` to find a base coordinate.
2. It picks shapes (`fill`, `build_sphere`, ...) and, for fine detail, sends many commands through `run_commands`.
3. It checks results with commands such as `execute if block x y z <block>`, which return "Test passed" or "Test failed".

## Troubleshooting

**`Failed to connect`**

- The server is not running, or RCON is not enabled. Check that `enable-rcon=true` is 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.1` may not reach it. Use the Windows host IP (the default gateway shown by `ip route show default`) as `MC_RCON_HOST`, or switch WSL to mirrored networking (`networkingMode=mirrored` in `.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.
- `run_command` also allows dangerous commands such as `stop`, `op`, and `ban`. Only connect to servers you own.
- There is no undo. Back up the world before large builds. `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

```sh
pnpm check   # type check
pnpm start   # start the MCP server on stdio
```

| File | Role |
|---|---|
| `src/rcon.ts` | Minimal RCON client |
| `src/builders.ts` | Pure functions that turn shapes into command lists |
| `src/index.ts` | MCP tool definitions |

## Roadmap

- Undo by saving a region before it is overwritten
- A command allow list and deny list
- A companion MCP that reports a user's installed mods

## License

[MIT](LICENSE)