hanweg/mcp-luanti-chat

MCP Chat for Minetest/Luanti

A Model Context Protocol (MCP) server that enables AI assistants to interact with Minetest/Luanti servers, send chat messages, execute commands, and build structures using WorldEdit.

Features

• 💬 Chat Integration: Send and receive chat messages
• 🎮 Command Execution: Execute server commands with privilege management
• 🏗️ WorldEdit Building: Full integration with WorldEdit for AI-assisted construction
• 👤 Virtual Player: Persistent "Claude" player for command execution
• 💾 Position Persistence: WorldEdit positions saved across server restarts
• 🔧 Robust Error Handling: Graceful fallback for compatibility issues

Dependencies

Minetest Mods

• WorldEdit - Required for building commands
• WorldEditAdditions - Optional, for extended commands

Python Requirements

• Python 3.10+
• MCP SDK
• aiohttp

Installation

1. Install the Minetest Mod

Place the mcp_chat folder in your Minetest mods directory:

cp -r mcp_chat ~/.minetest/mods/

Or for a specific game:

cp -r mcp_chat /path/to/minetest/worlds/yourworld/worldmods/

2. Configure Minetest

Add to your minetest.conf:

secure.enable_security = true
secure.http_mods = mcp_chat
mcp_chat.port = 8081
mcp_chat.relay_chat = true
mcp_chat.allow_commands = true

3. Install the MCP Server

Using uv (recommended):

cd mcp-luanti-chat
uv venv
uv pip install -e .

Using pip:

cd mcp-luanti-chat
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

4. Configure Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "minetest-chat": {
      "command": "/absolute/path/to/mcp-luanti-chat/.venv/bin/python",
      "args": ["-m", "mcp_chat_minetest"],
      "cwd": "/absolute/path/to/mcp-luanti-chat"
    }
  }
}

Usage

1. Start Minetest with the mcp_chat mod enabled
2. Start Claude Desktop - the MCP server will start automatically
3. Use the tools to interact with your Minetest world

Available MCP Tools

send-chat

Send messages or execute commands. Commands starting with / are automatically executed.

Examples:
- Send chat: "Hello players!"
- Execute command: "//set stone"

execute-command

Execute server commands directly.

Parameters:
- command: Command name (e.g., "/set" for WorldEdit)
- params: Command parameters (e.g., "stone")

get-players

Get list of connected players with positions.

get-chat-history

Retrieve recent chat messages (limit: 1-50, default: 20).

get-server-status

Check server connection status.

get-worldedit-help

Get WorldEdit documentation and building examples.

Parameters:
- topic: "general", "examples", or building type ("castle", "house", "bridge")

get-worldedit-status

Check current WorldEdit selection (positions and volume).

WorldEdit Integration

The mod creates a virtual player "Claude" with WorldEdit privileges, enabling AI-assisted building without requiring a real player online.

Basic Building Workflow

1. Set position 1 (first corner):

   //fixedpos set1 100 10 100
   

2. Set position 2 (opposite corner):

   //fixedpos set2 120 20 120
   

3. Fill the region:

   //set stone
   

Common Building Commands

• //set <node> - Fill region with a node
• //replace <old> <new> - Replace nodes
• //sphere <radius> <node> - Create sphere at pos1
• //cylinder y <height> <radius> <node> - Create cylinder
• //copy x/y/z <amount> - Copy region
• //stack x/y/z <count> - Stack region

Minetest Node Names

Common nodes for building (NOT Minecraft blocks):

• Basic: stone, cobble, dirt, sand, wood
• Glass: glass, obsidian_glass
• Decorative: stonebrick, sandstone, brick
• Special: water_source, lava_source, air

Example:

"Build an outrageous tower with the base centered on x, y, z"

Project Structure

mcp-luanti-chat/
├── mcp_chat/                 # Minetest mod
│   ├── init.lua             # Main mod code
│   ├── mod.conf            # Mod metadata
│   └── settingtypes.txt   # Configuration options
├── mcp_chat_minetest/       # MCP server
│   ├── __init__.py
│   ├── server.py           # MCP server implementation
│   └── worldedit_docs.py  # WorldEdit documentation
├── pyproject.toml           # Python package configuration
└── CLAUDE_DESKTOP_PROMPT.md # System prompt for Claude

Virtual Player System

The mod implements a virtual player "Claude" that:

• Has WorldEdit privileges automatically
• Maintains persistent positions across restarts
• Cannot access dangerous commands (e.g., //lua)
• Works without any real players online

Troubleshooting

Commands fail with "player object" errors

The mod includes automatic fallback to direct API calls for common WorldEdit commands. Use //fixedpos instead of //pos1 or //pos2 without coordinates.

HTTP API not available

Ensure secure.http_mods = mcp_chat is in your minetest.conf.

Connection issues

1. Check firewall settings for port 8081
2. Verify the MCP server is running
3. Check Minetest debug.txt for error messages

Security

• Commands are executed with controlled privileges
• The virtual player cannot access server-level commands
• All actions are logged for audit purposes
• HTTP communication is local-only by default

Credits

• WorldEdit by Uberi - Core building functionality
• WorldEditAdditions by sbrl - Extended WorldEdit commands
• Built with Model Context Protocol by Anthropic

License

MIT License - See LICENSE file for details