Minecraft Command Execution Server

An MCP (Model Context Protocol) server that enables Claude to execute Minecraft commands and get tab completions through the MasterControl API.

Features

This MCP server provides two tools:

1. execute_command

Execute any Minecraft command remotely as the authenticated player.

• Player must be online and on a server
• Player receives in-game notification when commands are executed
• Returns command output or error messages
• To get help: Append "help" to any command (e.g., "island help", "island upgrade help")

Examples:

execute_command("gamemode creative")
execute_command("island help")              # Shows island command help
execute_command("island upgrade help")      # Shows upgrade subcommand help
execute_command("island upgrade speed 5")

2. tab_complete

Get tab completion suggestions for partial commands.

• Discover available commands and subcommands
• Find valid arguments and parameters
• Works exactly like pressing Tab in Minecraft

Examples:

tab_complete("gamemode ")   # Returns: survival, creative, adventure, spectator
tab_complete("island ")     # Returns: available island subcommands

Prerequisites

• Python 3.10 or higher
• uv package manager (install here)
• A running MasterControl server with the command API
• Valid API key for your Minecraft player

Installation

1. Clone the repo:

   git clone https://github.com/<your-user>/minecraft-mcp-server.git
   cd minecraft-mcp-server
   

2. Install dependencies:

   uv sync
   

3. Configure environment variables:

   cp .env.example .env
   

4. Edit .env with your settings:

   # Required: Your Midnight API key
   MIDNIGHT_API_KEY=your-api-key-here
   
   # Optional: MasterControl API URL (defaults to localhost:8080)
   MIDNIGHT_API_URL=http://your-server:8080/api/v2
   

Usage

Testing Locally

Run the server directly to test:

uv run server.py

It will wait for stdio input — that's expected for an MCP server. Ctrl+C to exit.

Integrating with Claude Code

Add the server to Claude Code (use the absolute path to your cloned repo):

claude mcp add midnight \
  --transport stdio \
  --env MIDNIGHT_API_KEY=your-key-here \
  --env MIDNIGHT_API_URL=http://localhost:8080/api/v2 \
  -- uv --directory /absolute/path/to/minecraft-mcp-server run server.py

Verify Installation

In Claude Code, check that the server is running:

/mcp

You should see midnight listed with status ✓ Connected.

Example Conversations

Execute Commands:

You: "Change my gamemode to creative"
Claude: [Uses execute_command("gamemode creative")]
        ✓ Command executed successfully

Get Command Help:

You: "How do I use the island upgrade command?"
Claude: [Uses execute_command("island upgrade help")]
        Shows the help output for island upgrade

Explore Commands:

You: "What island commands are available?"
Claude: [Uses tab_complete("island ")]
        Lists: upgrade, create, delete, invite, members...

Configuration

Environment Variables

Variable	Required	Default	Description
MIDNIGHT_API_KEY	Yes	-	Your player's API key
MIDNIGHT_API_URL	No	http://localhost:8080/api/v2	MasterControl API base URL

API Endpoints

• POST /api/v2/command/execute — Execute commands
• POST /api/v2/command/tabComplete — Get tab completions

Troubleshooting

"MIDNIGHT_API_KEY environment variable not set!"

Create a .env file:

echo "MIDNIGHT_API_KEY=your-key-here" > .env

"Failed to execute command"

Check that:

1. MasterControl API is running
2. API key is correct
3. Player is online and on a server (not in proxy limbo)

Security

• Never commit .env — it contains your API key (already excluded via .gitignore)
• Commands execute with your player's permissions
• The AI can run any command you can run in-game