haksnbot-tools

An MCP (Model Context Protocol) server that gives Claude the ability to play Minecraft. Built on Mineflayer, this tool lets Claude Code (or any MCP-compatible AI) control a Minecraft bot with 40+ actions.

Part of the Haksnbot suite: This project was originally developed as part of Haksnbot, an autonomous Minecraft bot. The suite includes four repos that work together: haksnbot-tools (this repo - Minecraft bot control), haksnbot-mind (the autonomous agent), haksnbot-admin (server administration), and haksnbot-memory (persistent memory). Each can be used independently, but they're designed to work together.

Features

• Full bot control - Movement, combat, building, crafting, inventory management

• Microsoft authentication - Works with online-mode servers

• Pathfinding - Automatic navigation using mineflayer-pathfinder

• Auto-reconnect - Handles disconnections with exponential backoff

• Vision - 3D rendered screenshots of what the bot sees

• Villager trading - Browse and execute trades

• Shop integration - Works with QuickShop-Hikari plugin for player economies

Related MCP server: agent-skill-loader

Installation

git clone https://github.com/haksndot/haksnbot-tools.git
cd haksnbot-tools
npm install

Usage with Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/path/to/haksnbot-tools/src/index.js"]
    }
  }
}

Then in Claude Code:

> Connect to my Minecraft server at mc.example.com as "ClaudeBot"
> What's around me?
> Find some oak trees and chop wood
> Craft a crafting table and wooden pickaxe

Available Tools (40+)

Connection

Status & Observation

Movement

Communication

Inventory

Containers

Crafting

Combat & Interaction

Sleep

Building

Villager Trading

Mounts & Vehicles

Economy (QuickShop-Hikari)

Vision

Authentication

Offline-mode servers

connect to localhost as "MyBot"

Online-mode servers (Microsoft auth)

connect to mc.example.com as "myemail@outlook.com" with microsoft auth

On first connection, enter the device code at microsoft.com/link. Tokens are cached for future use.

# Manage auth tokens
node auth.js status myemail@outlook.com
node auth.js login myemail@outlook.com
node auth.js logout myemail@outlook.com

Auto-Reconnect

Automatic reconnection with exponential backoff:

• Initial delay: 2 seconds

• Max delay: ~5 minutes

• Max attempts: 10

Use disconnect to fully stop the bot.

Plugin Integrations

These tools were originally developed for a server running GriefPrevention and QuickShop-Hikari plugins. The bot has built-in support for these plugins, but all features work without them - they gracefully degrade when the plugins are not present.

GriefPrevention (Claim Protection)

The bot automatically detects claim protection when performing actions. On servers with GriefPrevention, the bot:

• Checks claim ownership before modifying blocks or containers

• Respects trust levels (uses /trustlist to check permissions)

• Reports denials clearly so you know why an action failed

Tools with GriefPrevention awareness:

Without GriefPrevention: All tools work normally. The bot simply won't detect claim-based denials (vanilla protection like spawn protection still applies).

QuickShop-Hikari (Player Economy)

For servers with QuickShop-Hikari, the bot can query and interact with player shops. These features require the MC_SERVER_ROOT environment variable pointing to your Minecraft server directory.

Configuration:

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/path/to/haksnbot-tools/src/index.js"],
      "env": {
        "MC_SERVER_ROOT": "/path/to/minecraft-server"
      }
    }
  }
}

Shop tools:

Without QuickShop or MC_SERVER_ROOT: These three tools return a helpful error message: "QuickShop features require MC_SERVER_ROOT environment variable". All other tools work normally.

Graceful Degradation Summary

Requirements

• Node.js 18+

• For take_screenshot: OpenGL support (Mesa on Linux)

Dependencies

• mineflayer - Minecraft bot framework

• mineflayer-pathfinder - Pathfinding

• prismarine-viewer - 3D rendering

• @modelcontextprotocol/sdk - MCP server SDK

Related Projects

• haksnbot-mind - Autonomous Minecraft bot using Claude Agent SDK

• haksnbot-admin - Server administration MCP tools

License

MIT