dsh-minecraft-agent

A DeepSeek Harness plugin that lets an AI agent live and act autonomously in Minecraft. Give it a goal, and it perceives its surroundings, decides, and acts — moving, gathering, building — via a local LLM.

The key differentiator: zero API cost. The agent is driven by a local model (e.g. Qwen3.8 served by llama.cpp), not a cloud API. Everything runs on your own GPU.

An all-Chinese AI stack. The agent's intelligence runs on DeepSeek Harness (runtime, by DeepSeek) + Qwen models (LLM, by Alibaba) — both Chinese open-source projects. No Western cloud-AI dependency anywhere in the loop. (mineflayer is only the Minecraft protocol layer, from the upstream PrismarineJS ecosystem.)

让 AI agent 在《我的世界》里自主生活与行动：给它目标，它就能感知环境、决策、执行——移动、采集、建造。核心卖点是本地模型驱动、零 API 成本，且 AI 栈全国产（DeepSeek Harness + 通义千问 Qwen）。

Why this over Mindcraft?

Mindcraft is the established "AI plays Minecraft" project (~5k stars), but it is a monolithic runtime. This plugin re-implements the same capability the DeepSeek Harness way — as a set of composable plugins. The mineflayer/Minecraft abilities are not rewritten; they are sunk into a tool layer the agent calls through Harness.

	Mindcraft	dsh-minecraft-agent
Runtime	Monolithic	DeepSeek Harness plugins
Model	Cloud or local	Local-first (any OpenAI-compatible endpoint)
Architecture	Custom agent loop	Harness tools + Cordis services
Extensibility	Patch JS	Write a plugin

Plugins

This repo ships two plugins (a third is in progress):

Plugin	File	Role
mc-bot-service	src/mc-bot.ts	Cordis service: manages the mineflayer bot instance (connect, spawn, auto-reconnect, dispose).
mc-tools	src/mc-tools.ts	Registers agent-callable tools: mc_status (observe), mc_goto (navigate), mc_collect (mine/gather), mc_place (build), mc_attack (fight), mc_pickup (loot).
mc-loop (planned)	—	A persistent perceive→decide→act→observe loop so the bot runs continuously, not one-shot.

Requirements

• DeepSeek Harness (developer preview)
• Node.js 22.19+ / 24+
• A Minecraft server (Java edition). Offline mode is fine for a bot.
• An LLM endpoint. Any OpenAI-compatible URL works:
  • Local (recommended, free): llama.cpp / Ollama, e.g. http://localhost:8890/v1
  • Cloud: the public DeepSeek API

Quick start

1. Clone this repo next to (or inside) your DeepSeek Harness checkout.
2. Point Harness at your LLM and load the plugins via a patch:

DEEPSEEK_BASE_URL=http://localhost:8890/v1 DEEPSEEK_API_KEY=sk-local \
  pnpm dsh --profile headless --patch ./mc-bot.patch.yml "<your task>"

mc-bot.patch.yml is a ready-made example. It wires mc-bot-service and mc-tools into a headless agent. Edit host/port/username to match your Minecraft server.

3. The agent can now call mc_status, mc_goto, mc_collect, mc_place, mc_attack, mc_pickup. Try:

"Walk to the chest at (-35, 66, 72), then mine 5 oak logs and place them as a fence."

Local model setup (free)

The default assumption is a local llama.cpp server exposing an OpenAI-compatible API:

llama-server -m Qwen3.8-27B.gguf --host 0.0.0.0 --port 8890 -c 524288

Then set DEEPSEEK_BASE_URL=http://localhost:8890/v1 and any placeholder DEEPSEEK_API_KEY. No cloud key, no per-token billing.

Configuration

mc-bot-service accepts:

Key	Default	Description
host	localhost	Minecraft server address
port	25565	Minecraft server port
username	HarnessBot	Bot name (server must allow it / offline mode)
autoReconnect	true	Reconnect on disconnect

Examples

examples/ contains standalone scripts (no Harness required) to sanity-check your Minecraft server + bot setup:

• test-mineflayer.mts — connect and confirm spawn.
• test-pathfinder.mts — navigate to a hard-coded target using mineflayer-pathfinder.

Run them with npx tsx examples/test-mineflayer.mts after setting MC_HOST / MC_PORT / MC_USERNAME.

Roadmap

• Tool hardening: every tool body runs behind a try-catch + bot-alive guard, so a single failure returns an error string instead of hanging the agent
• Core tools: mc_collect, mc_place, mc_attack, mc_pickup (moving, gathering, building, fighting)
• mc-loop: continuous perceive→decide→act→observe loop so the bot runs autonomously, not one-shot
• More tools: craftRecipe, putInChest, takeFromChest, viewChest, useToolOn
• A demo video

License

MIT — see LICENSE.

---

A project by jcs130. Built on DeepSeek Harness and the mineflayer ecosystem.