MC Server Bot

NeoForge 1.21.x mod (Kotlin) that adds autonomous LLM-powered NPCs to Minecraft.

NPCs use a two-tier behavior system:

• Reflexes — instant reactions via vanilla Minecraft Goals (combat, eating, fleeing)
• Reasoning — LLM agent loop with tool use for complex decisions (crafting, farming, building, socializing)

Features

• Server-side NPC entities with player-like appearance
• Multi-provider LLM support (Claude, OpenAI, Ollama)
• 21 tools for world interaction (navigation, mining, crafting, farming, combat, trading)
• Structured persistent memory (locations, relationships, knowledge)
• YAML config for NPC personalities + in-game /npc commands
• Async LLM calls via Kotlin coroutines (no server thread blocking)
• NPC data persists across server restarts (name, memory, inventory)

Requirements

• Minecraft 1.21.11
• NeoForge 21.11.37-beta or later
• Java 23+
• The mod must be installed on both client and server

Quick Start

1. Install the mod

Drop the jar into the mods/ folder on both client and server.

2. Configure the LLM provider

On first launch, the server will stop and create a default config at:

config/mcserverbot/config.yml

Edit this file to set your LLM provider and API key:

llm:
  provider: "zhipu"            # claude, openai, zhipu, or ollama
  model: "glm-5"
  api_key: "${LLM_API_KEY}"   # reads from .env or environment variable

Create a .env file next to server.properties with your API key:

LLM_API_KEY=your-api-key-here

See docs/admin-guide.md for full configuration reference.

3. Create an NPC

In-game with operator permissions:

/npc create Henri
/npc personality Henri Tu es Henri, un garde courageux qui protège le village.

4. Talk to it

Just type in chat near the NPC. It hears messages within a 20-block radius and responds using the LLM.

Commands

Command	Description
/npc create <name>	Spawn an NPC at your position
/npc delete <name>	Remove all NPCs with that name nearby
/npc personality <name> <prompt>	Set the NPC's system prompt

All commands require operator permissions (level 2+). You must be OP to see and use them — run op <player> from the server console. See docs/admin-guide.md for details.

NPC Tools

NPCs can use these tools via the LLM agent loop:

Awareness

Tool	Description
check_inventory	List inventory contents
check_surroundings	Scan nearby blocks and entities
check_status	Check health, position, hunger
check_crop_status	Check crop growth at coordinates

Communication

Tool	Description
say	Send a chat message
give_item	Give an item to a nearby player
follow	Follow a player

Navigation & Construction

Tool	Description
navigate_to	Pathfind to coordinates
mine_block	Break a block
place_block	Place a block from inventory
build_structure	Build a wall, floor, or pillar

Crafting & Farming

Tool	Description
get_recipe	Look up a crafting recipe
craft	Craft an item (stub)
till_soil	Till dirt with a hoe
plant_seed	Plant seeds on farmland
harvest_crop	Harvest a mature crop

Items & Combat

Tool	Description
pickup_item	Pick up nearby dropped items
equip	Equip an item from inventory
attack	Attack a nearby entity

Memory

Tool	Description
remember	Store information (category/key/value)
recall	Retrieve stored information

Building from Source

./gradlew build

The mod jar is output to build/libs/.

License

WTFPL