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
npm install -g bind-alias-mcp
The server speaks MCP on stdio. Point any MCP client at it.
| 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.