# Minecraft Command Execution MCP 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](https://docs.astral.sh/uv/))
- A running MasterControl server with the command API
- Valid API key for your Minecraft player

## Installation

1. **Clone the repo:**
   ```bash
   git clone https://github.com/<your-user>/minecraft-mcp-server.git
   cd minecraft-mcp-server
   ```

2. **Install dependencies:**
   ```bash
   uv sync
   ```

3. **Configure environment variables:**
   ```bash
   cp .env.example .env
   ```

4. **Edit `.env` with your settings:**
   ```bash
   # 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:

```bash
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):

```bash
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:
```bash
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