minecraft-server-management-protocol-mcp by BridgerB - MCP Server

Minecraft Server Management Protocol MCP Server

An MCP (Model Context Protocol) server that provides tools for managing Minecraft servers via the Minecraft Server Management Protocol.

Features

Multiple Server Support: Connect to and manage multiple Minecraft servers
Comprehensive Tools: Full implementation of the Minecraft Server Management Protocol
Type-Safe: Written in TypeScript with full type definitions
WebSocket: Efficient JSON-RPC 2.0 over WebSocket communication

Requirements

Deno 2.0 or higher
Minecraft Server 1.21.9+ with management server enabled

Management server configured in server.properties:

management-server-enabled=true
management-server-host=0.0.0.0
management-server-port=9090
management-server-tls-enabled=false

Installation

Clone this repository:

cd /home/bridger/git
git clone <your-repo-url> minecraft-server-management-protocol-mcp
cd minecraft-server-management-protocol-mcp

Create your configuration file:
```
cp config.json.example config.json
```

Edit config.json with your server details:

{
  "servers": {
    "production": {
      "url": "ws://your-server-ip:9090",
      "secret": "your-40-character-secret-from-server.properties"
    }
  }
}

Usage with Claude Code

Adding the MCP Server

To add this server to Claude Code, run:

claude mcp add --scope user --transport stdio minecraft-server -- \
  deno run --unstable-net --allow-net --allow-read --allow-env \
  /home/bridger/git/minecraft-server-management-protocol-mcp/main.ts

Note: The --unstable-net flag is required because this server uses Deno's WebSocketStream API with header support, which is currently an unstable feature.

Removing the MCP Server

If you need to remove or update the server configuration:

claude mcp remove minecraft-server

Then re-add it with the command above.

Using the Tools

Once added, you can interact with your Minecraft servers through Claude Code:

> How many players are on the production server?
> Kick player "Griefer123" from production with message "Banned for griefing"
> Get the server status for production
> Add "NewPlayer" to the allowlist on production
> Send a message "Server restarting in 5 minutes" to all players

Available Tools

Player Management

minecraft_list_players - List all connected players
minecraft_kick_player - Kick a player with optional message

Server Control

minecraft_server_status - Get server status (version, players, state)
minecraft_save_server - Save the world to disk
minecraft_stop_server - Gracefully stop the server
minecraft_send_system_message - Send messages to players

Allowlist Management

minecraft_get_allowlist - Get all allowlisted players
minecraft_add_to_allowlist - Add players to allowlist
minecraft_remove_from_allowlist - Remove players from allowlist
minecraft_clear_allowlist - Clear entire allowlist

More Tools (TODO)

The following tool categories are planned:

Ban management
IP ban management
Operator management
Server settings (difficulty, max players, MOTD, etc.)
Gamerule management

Configuration

Server Configuration Format

{
  "servers": {
    "<server-name>": {
      "url": "ws://<host>:<port>",
      "secret": "<40-character-secret>"
    }
  }
}

server-name: A friendly name you choose (e.g., "production", "staging")
url: WebSocket URL to your Minecraft management server
secret: The management-server-secret from your server.properties

Finding Your Server Secret

The secret is in your Minecraft server's server.properties file:

grep management-server-secret /var/lib/minecraft/server.properties

Example output:

management-server-secret=ABCxyz123

Development

Running Tests

deno test

Running Locally

deno run --allow-net --allow-read --allow-env main.ts

Adding New Tools

Create a new file in tools/ (e.g., tools/bans.ts)
Export a registerBanTools(pool) function
Import and add to allTools in main.ts

Example tool structure:

export function registerBanTools(pool: MinecraftConnectionPool) {
  return [
    {
      name: "minecraft_list_bans",
      description: "Get all banned players",
      inputSchema: {
        type: "object",
        properties: {
          server: { type: "string", description: "Server name" },
        },
        required: ["server"],
      },
      handler: async ({ server }: { server: string }) => {
        const bans = await pool.request(server, "minecraft:bans");
        return {
          content: [{ type: "text", text: JSON.stringify(bans, null, 2) }],
        };
      },
    },
  ];
}

Architecture

main.ts                 # MCP server entry point
├── config.ts           # Configuration loader
├── websocket.ts        # WebSocket client & connection pool
├── types.ts            # TypeScript type definitions
└── tools/              # Tool implementations
    ├── players.ts
    ├── server.ts
    ├── allowlist.ts
    └── ...             # Add more tool files here

Troubleshooting

"Configuration file not found"

Make sure you've created config.json from config.json.example and it's in the project root.

"WebSocket connection error"

Verify your Minecraft server is running
Check that management-server-enabled=true in server.properties
Ensure the port (9090) is open in your firewall
Verify the URL format: ws://host:port (not wss:// unless TLS is enabled)

"JSON-RPC Error -32601: Method not found"

The Minecraft server doesn't support that method. Ensure you're running Minecraft 1.21.9 or higher.

"Request timeout"

The server isn't responding. Check:

Server is running and accessible
Management server is enabled and listening
Secret matches between config.json and server.properties

License

Unlicense (Public Domain)

Contributing

Contributions welcome! To add support for more Minecraft Server Management Protocol methods:

Add types to types.ts if needed
Create tool implementations in tools/
Register tools in main.ts
Update this README

BridgerB/minecraft-server-management-protocol-mcp