Bedrock Server Manager MCP Server

A comprehensive Model Context Protocol (MCP) server that provides natural language access to Bedrock Server Manager functionality. This server enables you to manage your Minecraft Bedrock Edition servers through AI assistants like Claude Desktop using simple conversational commands.

🚀 Features

Server Management

Server Lifecycle: Start, stop, restart, and monitor server status
Server Installation: Install new servers with custom configurations
Server Updates: Update servers to specific versions or latest releases
Server Validation: Verify server integrity and configuration

Player & World Management

Allowlist Management: Add/remove players from server allowlists
Player Permissions: View and manage player permission levels
World Operations: Reset worlds, export/import world files, install custom worlds
Global Player Lists: Manage global player lists across servers

Backup & Restore

Automated Backups: Create server and world backups on demand
Backup Management: List, prune, and manage backup files
Restore Operations: Restore servers from specific backup files
Export/Import: Export worlds and import custom content

Advanced Features

Add-on Management: Install and manage Bedrock add-ons
Plugin Control: Enable/disable plugins, reload configurations, trigger events
Scheduled Tasks: Create and manage cron jobs (Linux/macOS) or Windows tasks
System Monitoring: View system information and server process details
Configuration Management: Update server properties and service configurations

📋 Prerequisites

Python 3.8 or higher
Access to a running Bedrock Server Manager instance
Valid credentials for your Bedrock Server Manager

🛠️ Installation

1. Clone or Download

git clone <repository-url>
cd BedrockMCP

2. Create Virtual Environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Environment Configuration

Create a .env file in the project root:

# Required: Your Bedrock Server Manager API endpoint
BEDROCK_API_BASE=http://localhost:11325

# Required: Authentication credentials
BEDROCK_SERVER_MANAGER_USERNAME=your_username
BEDROCK_SERVER_MANAGER_PASSWORD=your_password

# Optional: Enable debug output for API responses
BEDROCK_DEBUG=false

Configuration Notes:

The default Bedrock Server Manager port is 11325
Replace localhost with your server's IP address if running remotely
Ensure your Bedrock Server Manager instance is running and accessible

🎯 Usage

Standalone Mode

python bedrock_mcp_server.py

Add --debug flag for detailed API response logging:

python bedrock_mcp_server.py --debug

With Claude Desktop

Open Claude Desktop Configuration
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add MCP Server Configuration

{
  "mcpServers": {
    "bedrock-server-manager": {
      "command": "/path/to/your/BedrockMCP/start_bedrock_mcp.sh",
      "args": []
    }
  }
}

Make Start Script Executable (macOS/Linux)
```
chmod +x start_bedrock_mcp.sh
```
Update Script Path Edit start_bedrock_mcp.sh and update the project path on line 4:
```
cd /your/actual/path/to/BedrockMCP
```
Restart Claude Desktop

🔧 Available Tools

The set of available tools and endpoints is evolving rapidly. For the most up-to-date list, please refer to the OpenAPI specification for the bedrock-server-manager or use natural language commands with your LLM assistant to discover current capabilities.

💬 Example Commands

Once configured with Claude Desktop, you can use natural language commands like:

Server Operations

"What servers do I have and what's their status?"
"Start my survival server"
"Stop the creative server and then restart it"
"What's the detailed status of my main server?"

Player Management

"Who's on the allowlist for my survival server?"
"Add Steve and Alex to the survival server allowlist"
"Remove Bob from the creative server allowlist"
"What are the player permissions on my server?"

Server Commands

"Send the 'list' command to my survival server"
"Tell all players on the creative server that the server will restart in 5 minutes"
"Change the difficulty to hard on my survival server"

Backup Operations

"Create a backup of my survival server"
"Show me all backups for the creative server"
"Restore my survival server from yesterday's backup"
"Delete old backups, keeping only the last 5"

World Management

"Reset the world on my testing server"
"Install the 'skyblock' world on my adventure server"
"Export the world from my survival server"

Advanced Operations

"Update my main server to the latest version"
"Install the better-spawning addon on all my servers"
"Create a daily backup job for my survival server"
"Show me the system information"

🔍 Troubleshooting

Connection Issues

Verify Bedrock Server Manager is running
```
curl http://localhost:11325/api/health
```
Check credentials in .env file
- Ensure username and password are correct
- Verify BEDROCK_API_BASE URL is accessible
Enable debug mode
```
python bedrock_mcp_server.py --debug
```

Common Problems

"Unable to fetch servers list"

Check if Bedrock Server Manager is running
Verify network connectivity to the API endpoint
Confirm authentication credentials

"Login failed"

Double-check username and password in .env
Ensure Bedrock Server Manager allows API access

Script permission errors (macOS/Linux)

chmod +x start_bedrock_mcp.sh

🧪 API Coverage Testing

To ensure all OpenAPI endpoints are mapped to MCP functions (and vice versa), this project includes automated coverage scripts:

Extract OpenAPI Endpoints:
- extract_openapi_endpoints.py fetches the OpenAPI spec from your running Bedrock Server Manager instance (host and port configurable) and outputs all endpoints with their operationIds to openapi_endpoints.json.
Extract MCP Functions:
- extract_mcp_functions.py scans bedrock_mcp_server.py for MCP-exposed functions (decorated with @mcp_tool_testable) and outputs them to mcp_functions.json.
Run Coverage Test:
- test_api_coverage.py (run with pytest) compares the two lists and reports any unmapped endpoints or functions.
Automated Workflow:
- run_api_coverage_check.py automates all the above steps.

How to Use

Run the coverage workflow and optionally specify the server host and port (defaults localhost and 11325):

python run_api_coverage_check.py [server] [port]

This will:

Generate openapi_endpoints.json and mcp_functions.json
Run the coverage test and print any missing or extra mappings

Requirements

pytest must be installed (see Dependencies below)

Purpose

This workflow helps keep your OpenAPI documentation and MCP implementation in sync, ensuring all endpoints are covered and documented.

📝 Dependencies

mcp (>=1.2.0) - Model Context Protocol implementation
httpx (>=0.24.0) - Modern HTTP client for API requests
python-dotenv (>=1.0.0) - Environment variable management
pytest (for API coverage testing)

🤝 Contributing

This project interfaces with Bedrock Server Manager. For issues related to the server manager itself, please refer to that project's repository.

📄 License

This project is provided as-is for educational and personal use. Please respect the licenses of the underlying Bedrock Server Manager and Minecraft Bedrock Edition.