bind-alias-mcp

BindAlias MCP

MCP bridge for the BindAlias Minecraft mod. Lets AI agents control Minecraft: query game state, take screenshots, execute aliases, manage recipes, read/write notes, and edit the per-save agent config.

Prerequisites

• Minecraft with the BindAlias mod loaded
• The mod's HTTP API enabled (listens on 127.0.0.1:25575 by default, with automatic port fallback)

Install in Zed

Add to your settings.json:

{
  "context_servers": {
    "bind-alias": {
      "command": {
        "path": "npx",
        "args": ["bind-alias-mcp"]
      }
    }
  }
}

Or with a local checkout:

{
  "context_servers": {
    "bind-alias": {
      "command": {
        "path": "node",
        "args": ["path/to/BindAlias-MCP/mcp_server.js"]
      }
    }
  }
}

Use --port N to match a non-default mod port:

"args": ["path/to/BindAlias-MCP/mcp_server.js", "--port", "25576"]

Zed spawns MCP servers at startup — reload Zed (zed-reload) after editing to pick up the new server.

Install via CLI

npx bind-alias-mcp
# or globally
npm install -g bind-alias-mcp

The server speaks MCP on stdio. Point any MCP client at it.

Tools

Tool	What it does
getFullState	Full game state snapshot — screen, world, dimension, player pos/rot, health, hotbar, inventory, effects, nearby players, plus drained chat/mod/sound/recipe messages
getScreenshot	Take a screenshot, return as base64 PNG with the standard state envelope
runAlias	Execute a chain of aliases. Optional nap (client ticks) defers the response while the game keeps running.
defineAlias	Define a new alias at runtime (requires being in a world).
readCFG	Read the per-save agent config (saves/<save>/bind-alias/agent.cfg). Requires being in a singleplayer world.
writeCFG	Overwrite the per-save agent config and reload. Requires being in a singleplayer world.
readNotes	Read a file from the per-save agent directory (saves/<save>/bind-alias/). Plain filenames only, no paths.
writeNotes	Write a file to the per-save agent directory. Plain filenames only, no paths.
listRecipes	List unlocked recipes (diff or by query). Only works with a recipe-book screen open (inventory, crafting table, furnace, …).

The tool descriptions only cover the wire protocol — see the mod docs and the system prompt patch for the full alias reference.

Agent system prompt patch

The tool descriptions this server advertises only cover the wire protocol — the fixed facts the tools themselves must know. The gameplay knowledge (the full alias catalog, screens, variables, per-world cfg semantics) changes with the mod and your world, so it lives separately in a flexible patch:

• PATCH TO YOUR PROJECT RULE.md — paste this into your agent's system prompt / project rules (e.g. Zed's AGENTS.md) to teach it how to drive the game.

Related

• BindAlias mod — the Minecraft mod this server bridges to
• MCP Registry — registered as io.github.Prohect/bind-alias-mcp