MinecraftBot

An autonomous Minecraft Java Edition player built on Mineflayer, MCP, and a verifiable Skill state machine. It joins servers as a standalone game character, perceives the world primarily through protocol-level structured data, and can navigate, gather, craft, fight, build, and continuously execute long tasks.

Recommended for use with the standalone Demiurge desktop Agent: Demiurge provides the persona, current LLM, long-term memory, desktop image chat, and high-level decisions; MinecraftBot handles server connection, structured perception, and reliable execution. The two projects are independent of each other and do not require Minecraft client mods.

Two operating modes

The project never commits .env, API keys, run logs, the SQLite memory database, or local Minecraft data.

Related MCP server: Minecraft Dedalus MCP

Implemented capabilities

• Offline or Microsoft identity connection, auto-reconnect, fixed character name.

• Perception of players, inventory, equipment, entities, blocks, time, weather, and events.

• World summaries, spatial location memory, task persistence, and disconnection recovery.

• External LLM API planning, failure recovery, and strict JSON validation.

• Accurate item, block, mob, and recipe database, plus recursive material calculation.

• Local guide RAG, can import Markdown/TXT guides.

• Skill resource locks, priority preemption, timeout, cancellation, progress, retry, and result verification.

• Navigate, follow, mine, collect, place, craft, smelt, fight, escape, eat, deliver, access containers, build, and explore.

• Low-health escape, being stuck, inventory full, and low tool durability monitoring.

• SQLite memory, JSON health endpoint, structured logging.

• Depth-buffer geometry reprojection, residual-region clustering, known-change masking, and optional VLM analysis interface.

• Mock LLM and Mock Executor to test the core system without an MC server or API key.

• MCP stdio tools/resources, game event notifications, and a Demiurge persona, session, and memory loop.

Runtime structure

PCL（FuQiang） ───────公网──────> 腾讯云 Minecraft Server
                                      ↑
本机 Demiurge ──MCP stdio──> Mineflayer AI_Player
      │ 当前角色/长期记忆           │ 结构化感知/RAG/Skill Runtime
      └────唯一 LLM 规划与对话──────┘

Requirements

• Minecraft Java server.

• Node.js 22.13 or later.

• pnpm 10 or later, or enable via Corepack.

• MCP mode requires Demiurge with an LLM configured; only needed for standalone mode when OpenAI-compatible API is required.

Local installation

corepack enable
pnpm install
cp .env.example .env

At minimum, configure these when running standalone:

MC_HOST=127.0.0.1
MC_PORT=25565
MC_USERNAME=AI_Player
MC_AUTH=offline
MC_OWNER=FuQiang

LLM_MODE=api
LLM_BASE_URL=https://你的API地址/v1
LLM_API_KEY=你的密钥
LLM_MODEL=你的模型名

Run the offline normal first:

pnpm typecheck
pnpm test
pnpm smoke

Start development mode:

pnpm dev

Production mode:

pnpm build
NODE_ENV=production pnpm start

Using Demiurge (recommended)

Build the two projects separately:

# 本项目
pnpm install --frozen-lockfile
pnpm build

# Demiurge（单独克隆）
git clone https://github.com/Dancncn/Demiurge.git
cd Demiurge
npm install
npm run tauri dev

Building Demiurge on Windows also requires Rust stable(MSVC), the "Desktop development with C++" component in Visual Studio 2022 Build Tools, and the Windows SDK; if link.exe is missing, be sure to install these first.

In Demiurge's "Settings → Minecraft", select this project directory and the Node.js executable, fill in the Tencent Cloud server public address, the AI game username AI_Player, and the main user game name FuQiang, then turn on "Enable. After saving, Demiurge will auto-start the MCP child process; disable it again then stop/restart.

MCP mode forces MCP_STDIO=true and LLM_MODE=mock, but here mock only means Mineflayer does not call the internal planning model. All planning, persona, and dialogue come from the real LLM currently configured in Demiurge. Public and private conversation both carry the real speaker's username, channel, owner flag, and scene. Typing AI_Player，follow me naturally names the character with no modifiers; unnamed public messages are interpreted by the LLM based on context. Conversation and key experiences go into the same memory namespace as this persona; manually recording scene, channel, player username, and owner flag, the long-term memory is forced by code rather than trusting the extraction model to keep them.

The desktop input supports multi-image JPEG, PNG, GIF, and WebP (single 10 MB, 20 MB total); images go only to Demiurge's current mode, not through game chat.

See the Demiurge Integration Guide for full configuration and joint acceptance.

Minecraft server configuration

server.properties:

online-mode=false
server-port=25565
server-ip=
white-list=true

After restarting the server, run this in the console:

whitelist on
whitelist add FuQiang
whitelist add AI_Player

Offline mode does not have reliable account identity. The Tencent Cloud security group should only open TCP:25565 to your public IP, or connect over Tailscale/WireGuard; the whitelist cannot prevent username impersonation.

In-game commands

MC_OWNER defines the owner. Comparison is case-insensitive, but events and memory preserve the player's exact displayed username. The model separates the master player from other players in relationships, permissions, and memory. Other players can still use public chat, private messages, and request ordinary recursion. In MCP mode, natural-language messages go through Demiurge's current role for judgment/handling; in standalone, only owner messages that explicitly name the AI username are executed.

AI_Player，帮助
AI_Player，状态
AI_Player，停止
AI_Player，跟着我
AI_Player，去 120 64 -30
AI_Player，收集16个橡木
AI_Player，制作一把石镐并交给我
AI_Player，探索周围区域

The fixed @-prefix has been removed. Call it by the configured AI game username; private messages are naturally considers addressed to the bot, and non-named public chat is a decision left to the model.

Guide knowledge base

The interactive registry and precise network raw data come from minecraft-data, not from vector search. Natural-language wikis can be imported in bulk:

pnpm knowledge:index ./my-guides

Supports recursive reading of .md and .txt. By default it uses local cached hashes, with no extra embedding API cost; the vector implementation in GuideRag can be replaced later.

Health check

By default listens only on the local port:

GET http://127.0.0.1:3008/health
GET http://127.0.0.1:3008/metrics

Set HEALTH_PORT=0 to disable it. Do not expose the health port directly to the public network.

Console vision

The agent system does not rely on screenshots. src/vision currently implements:

• Geometric reprojection from previous frame depth and camera matrix.

• Original vs. background RGB residual.

• Known action region adversarial.

• Alternation region clustering and threshold filtering.

• Anomaly events and optional VLM analysis.

Mineflayer itself does not provide raw RGB and depth buffers, so enabling vision needs an offscreen renderer or similar source for frames. The project includes HttpFrameSource. Set VISION_ENABLED=true and VISION_FRAME_URL=http://127.0.0.1:端口/frame to use. If no external frame source is thread, keep VISION_ENABLED=false and continue with structured perception.

Security boundaries

• PVP disabled by default: ALLOW_PVP=false.

• Can disable throwing items : ALLOW_DROP_ITEMS=false.

• A single plan is limited to at most MAX_PLAN_STEPS steps.

• Single action distance is limited by MAX_ACTION_DISTANCE.

• Standalone mode only accepts tasks where the owner explicitly names the AI username; MCP mode relies on Demiurge to decide whether unhandled public messages need a response.

• The LLM can only choose registered Skills; parameters go through Zod validation.

• API key is only read from environment variables, and logs redact anonymous fields.

• Emergency escape has priority over the normal queue and can preempt movement.

For more detail, make Tencent Cloud deployment steps: see docs/DEPLOY_TENCENT.md and MCP making: docs/SKILLS.md, vision integration rules: docs/VISION.md.

Project boundaries

• Target is Minecraft Java Edition; protocol connectivity given by Mineflayer.

• Spatial data is the default active path; local vision and VLM need an extra source socket.

• Micro perspective and per-frame skill detail is done by the executor and Skill; the LLM does not process pixel frames.

• Offline servers cannot reliably verify usernames; restrict port source or use a private network.

• In MCP mode, public messages can always trigger evaluation by the LLM; assess API cost by the active player count.

Development & testing

pnpm typecheck
pnpm test
pnpm build
pnpm smoke

Tests do not require a real Minecraft server or external LLM key; Mock Executor and Mock LLM cover all high-level paths in planning, Skills, memory, MCP notification, and residual vision.