<p align="center"><img src="docs/images/icon.png" width="160" alt="Ashlar icon"></p>

Ashlar

English | 简体中文

AI building tools for Minecraft Paper servers - no SSH, no LAN world: one jar plus one URL.

Built by Claude through this MCP.

Ashlar is a Paper plugin plus a Node MCP server. Point an AI client - Claude Desktop, Claude Code, OpenCode, Cursor, or anything else that speaks MCP - at the MCP server, and it gets nine tools to survey terrain, render images of the world, build in bulk, inspect exact block data, snapshot/restore regions, and run console commands. No mods, no SSH access to the host, no need to run the world on your own machine: the plugin runs inside your existing Paper server (a panel-hosted one works fine) and talks to the MCP server over a WebSocket. Players who have no MCP client at all can instead just type /ashlar <request> in chat and get an answer from the plugin's own built-in assistant - no Node process or inbound port needed for that path; see In-game assistant below.

How it works

AI client                MCP server                 Paper plugin
(Claude/ChatGPT/...)     (Node, mcp-server/,         (Java, plugin/ - owns the
                          a protocol adapter)         tool layer: descriptions,
                                                       schemas, result text,
                                                       execution)

   mc_* tool call  --->  tool_catalog/tool_call  --->   main-thread block
   (stdio or HTTP)       over WebSocket RPC             writes, tick-budgeted
                         (ws:// / wss://)
        <---  text/image result  <---  JSON result / progress events

player's /ashlar  --->  plugin's built-in assistant  --->  model API (DeepSeek by default)  --->  same tools above

The tool layer lives entirely in the plugin, not in the MCP server: ashlar-mcp fetches the tool catalog (descriptions, JSON schemas, and the server-level instructions text) from the plugin at startup and just forwards calls, so there is one definition of every tool, reused by any MCP client and by the in-game assistant alike. The /ashlar path needs no Node process and no inbound port at all: the plugin calls the model API directly (an outbound HTTPS connection) and runs the same in-process tool layer the MCP adapter forwards to.

• Coarse-grained tools: one mc_build call places up to 500,000 blocks, instead of the AI placing blocks one at a time.
• All block edits run on the server's main thread, spread across ticks under a per-tick time budget, so a large build does not freeze the server or lag players.
• Physics is off while writing (sand does not fall, water does not flow); a connection pass afterward lets fences/panes/walls/stairs connect to their neighbours, and any block left without support is reported back as a warning instead of silently popping off.
• mc_build can snapshot the affected region before writing, so any build can be rolled back with mc_restore.

The tools

| Tool | What it does | |---|---| | mc_status | Server/plugin health and queue length. | | mc_players | Online players with position and facing ("here", "in front of me", "at my feet"). | | mc_survey | Terrain survey of an x/z area: heightmap image plus exact numbers (min/max/median height, surface mix, largest flat zone); format:"text" for an ASCII map. | | mc_render | PNG image of a region: top view, north/south/east/west facades, a slice, or a heightmap (top/heightmap are area-priced, any y range). | | mc_build | Places blocks in bulk (cuboid fills with modes replace/keep/outline/hollow/walls, individual blocks and sign text, plus lettering rendered by the plugin via text); the only tool that builds. | | mc_inspect | Exact block contents of a region (statistics, ASCII slice, sign text). | | mc_snapshot | Save a region before changing it (or list saved snapshots). | | mc_restore | Roll a region back to a snapshot. | | mc_command | Run a server console command and return its output (escape hatch). |

Typical flow: mc_players (if the request is relative to a player) -> mc_survey or mc_render to see the site -> mc_snapshot -> mc_build -> mc_render/mc_inspect to verify -> mc_restore if it went wrong. Coordinates: X grows east, Z grows south, Y grows up; from/to corners are inclusive.

Install (three steps)

1. Install the plugin

1. Download ashlar-0.4.9.jar from the Releases page into your server's plugins/ folder.
2. Start the server once, then stop it. The plugin refuses to fully start on this first run - it writes a default plugins/Ashlar/config.yml and disables itself because the token is empty.
3. Edit plugins/Ashlar/config.yml:
   • mode: how this server is used - both (default: MCP clients and /ashlar), mcp (MCP clients only), ingame (/ashlar only) or external (see In-game assistant). Only using /ashlar in game, no AI client? Set mode: ingame, skip the rest of this list and go straight to that section: no port is opened and no token is needed.
   • server.token: a long random value, e.g. openssl rand -hex 24. Unless mode is ingame, the plugin refuses to start if this is missing or shorter than 16 characters.
   • server.port: an idle TCP port your host/panel exposes.
   • server.allowed-ips: optional. If the MCP server runs somewhere with a fixed public IP (a VPS), put that IP here. If it runs on your own PC behind a typical home connection, your IP changes and an allow-list would lock you out - leave it empty and rely on the token, which is the real authentication. See Security for what an empty list means and how to tighten it anyway.
4. Restart the server.

2. Have Node on the client machine

There is nothing to install by hand. The client configs below start the MCP server with npx -y ashlar-mcp, which downloads it from npm on first launch and caches it; the only requirement is Node >= 22 on the machine that runs your AI client. (ashlar-mcp 0.4 needs plugin 0.3 or newer and exits with a clear message otherwise. If you would rather have a fixed path, npm install -g ashlar-mcp once and point the configs at the resulting ashlar-mcp binary.)

3. Connect a client

Claude Desktop

Edit claude_desktop_config.json (Settings -> Developer -> Edit Config) and add:

{
  "mcpServers": {
    "ashlar": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "ashlar-mcp", "--stdio"],
      "env": {
        "MC_PLUGIN_URL": "ws://<your-server-ip>:8765",
        "MC_PLUGIN_TOKEN": "<the token from config.yml>"
      }
    }
  }
}

Use an absolute path to npx (which npx) - Claude Desktop does not inherit your shell's PATH. After adding the server, open its "Tool access" settings and pick "Tools already loaded"; the alternative, "Load tools when needed", is unreliable in practice (the model can end up seeing only one or two mc_* tools). Claude Desktop starts two instances of the MCP server per configured connector - this is normal and harmless.

Claude Code

claude mcp add --scope user --transport stdio ashlar \
  -e MC_PLUGIN_URL=ws://<your-server-ip>:8765 \
  -e MC_PLUGIN_TOKEN=<the token from config.yml> \
  -- npx -y ashlar-mcp --stdio

OpenCode

Add to opencode.json (in the project, or ~/.config/opencode/opencode.json for every project):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ashlar": {
      "type": "local",
      "command": ["npx", "-y", "ashlar-mcp", "--stdio"],
      "environment": {
        "MC_PLUGIN_URL": "ws://<your-server-ip>:8765",
        "MC_PLUGIN_TOKEN": "<the token from config.yml>"
      },
      "enabled": true
    }
  }
}

A project-level opencode.json contains the token, so keep it out of git (or use the global file). For an HTTP-mode server (below) use "type": "remote" with "url": "http://<host>:3000/mcp" and "headers": {"Authorization": "Bearer <MCP_HTTP_TOKEN>"} instead.

Remote/HTTP mode (for a VPS-hosted MCP server)

Run the MCP server itself over HTTP instead of stdio, e.g. on the same VPS as a panel-hosted Paper server:

MC_PLUGIN_URL=ws://127.0.0.1:8765 \
MC_PLUGIN_TOKEN=<plugin token> \
MCP_HTTP_TOKEN=<a second, separate long random token> \
npx -y ashlar-mcp --http

Clients that can send custom headers authenticate with Authorization: Bearer <MCP_HTTP_TOKEN> against POST /mcp. Clients that cannot set headers (such as a remote MCP connector configured with only a URL) can instead use POST /mcp/<MCP_HTTP_TOKEN>, which puts the token in the path. GET /healthz is unauthenticated and reports whether the MCP server currently has a live connection to the plugin.

Put a TLS-terminating reverse proxy in front of the HTTP port - the server itself only speaks plain HTTP. Claude Desktop's remote connector setup requires HTTPS. A minimal Caddy config does this in one line:

mcp.example.com {
    reverse_proxy 127.0.0.1:3000
}

First build

A worked example. The user says:

Survey the area around me and build a small stone cottage with glass windows and a sign over the door saying "Home". Snapshot first.

The model's tool calls, in order:

1. mc_players {} - finds the caller's block position, e.g. pos: [104, 65, -212], and facing.
2. mc_survey { "from": [84, -232], "to": [124, -192] } - a 40x40 area centered on the player; returns a heightmap image plus text such as Largest flat zone (+/-1 block): 12x9 at x=98..109 z=-220..-211, y=65.
3. mc_snapshot { "action": "create", "from": [98, 64, -220], "to": [109, 71, -211] } - captures the build region; returns a snapshot id like snap-20260914-101532-7c2a.
4. mc_build with a handful of fills (floor, walls via mode: "walls", roof) using minecraft:stone_bricks, window openings via a second fills entry with minecraft:glass, and one blocks entry for minecraft:oak_door plus one for a sign (minecraft:oak_wall_sign[facing=south] with sign.front: ["Home"]) placed in the air block above the door frame.
5. mc_render { "from": [98, 64, -220], "to": [109, 71, -211], "view": "south" } - a facade image to check the result.

If the door or sign ended up without solid support behind it, mc_build's response text ends with a block like:

WARNINGS (blocks that would fall or pop off in vanilla, including ones next to something you just removed; physics is disabled so they stay - fix them):
  1x minecraft:oak_wall_sign[facing=south] at 103,68,-215: no solid block behind it

The model is expected to read this and fix the flagged blocks (or explain the trade-off) before telling the user the build is done - physics being off means nothing falls on its own.

In-game assistant (no AI client needed)

Everything above needs an AI client on the player's own machine. /ashlar <request> is the alternative: the plugin runs the assistant itself, inside the same process as everything else, through the same nine tools - without anyone needing Claude Desktop, Claude Code, Cursor, any other MCP client, or a separate Node process. This is for the players and friends on your server who do not run an AI client at all - the server owner sets one API key and pays for the model API; everyone else just types in chat.

Setup

1. Plugin only. Set agent.model.api-key in plugins/Ashlar/config.yml to a DeepSeek key from platform.deepseek.com (the defaults already point at deepseek-flash), restart the server, and /ashlar works - no other process to run:

   mode: both                # default: MCP clients and /a