pm-minecraft

A self-contained Minecraft survival body for MCP clients.

It runs Mineflayer, Prismarine Viewer, a local web UI, and a Streamable HTTP MCP server.

It does not contain an agent, model, or cognitive runtime. Only some minimal instruction telling your agent of choice how to use the MCP, look at screenshots and make custom TypeScript scripts, that can be executed via MCP.

Huge thanks to https://github.com/minedojo/voyager and https://github.com/Mega-Gorilla/Discovery :3

This is part of an ongoing effort on my side to make a fun cognitive architecture AI companion that can play minecraft with you. Also works as standalone ^_^

Setup

Requirements: Windows PowerShell, Node.js 20+, Python 3.12 through py, and a reachable Minecraft Java 1.19.x server with the character in survival mode.

Set-Location C:\workspace\pm-minecraft-mcp
.\setup.ps1

The setup follows the shared PM workflow: it uses uv to create this repository's Python 3.12 .venv, syncs its lockfile, and installs locked Node packages. scripts/setup.ps1 remains as a compatibility wrapper.

If it doesn't work tell your coding agent to fix it.

Minecraft

I stole the setup from https://github.com/Mega-Gorilla/Discovery.

I have never modded Minecraft manually, what works for me:

• Download Prism
• Install 1.19.4
• Install Fabric Loader 0.19.3
• Install these mods via Prism:
  • Fabric API
  • CompleteConfig
  • Mod Menu
  • Multiplayer Server Pause (Forge)
• Make Survival World, Cheats Enabled, Peaceful
• Enter and "Open to LAN" on Port 12345

Create and start a character

.\scripts\init_character.ps1 `
  -Name Floppa `
  -AgentRoot C:/Temp/Floppa `
  -ArtifactRoot C:/Temp/Floppa/artifacts/minecraft

.\scripts\start_minecraft_mcp.ps1 `
  -Name Floppa `
  -MinecraftHost 127.0.0.1 `
  -MinecraftPort 12345 `
  -AgentRoot C:/Temp/Floppa `
  -ArtifactRoot C:/Temp/Floppa/artifacts/minecraft

The initializer creates the agent workspace, memory/minecraft/, drafts/, skills/, lib/minecraft.ts, and .mcp.json. The launcher prints the local web UI, Prismarine viewer, and MCP URLs. For multiple characters, use unique -WebPort, -ViewerPort, and -McpPort values.

Stop an instance with:

.\scripts\stop_minecraft_mcp.ps1 -ArtifactRoot C:/Temp/Floppa/artifacts/minecraft

Then use it from the workspace:

Set-Location C:/Temp/Floppa
codex

Codex reads .mcp.json. Prompt it to use the minecraft server; state logs and screenshots are under ./artifacts/minecraft.

Perception and viewer modes

minecraft_find_block defaults to require_visible: true. This is the normal survival setting: it returns only blocks with an unobstructed ray from the character's head. An agent must explore, move to a better viewpoint, or use a different observation when it cannot see the target. For long-range planning, set require_visible: false; the result is a loaded-world location only and must still be reached and visibly verified before mining.

Cool stuff

Here is the WebUI where you can manually control the character or look at how the coding agent uses the MCP.

<img src="./docs/webui.png">

And here is Codex describing my character's skin. Prismarine only renders default Steve :(

<img src="./docs/agent.png">

Development

npm test
npm run build
.\.venv\Scripts\python.exe -m compileall mcp