Pebblehost Minecraft MCP Server

A Model Context Protocol (MCP) server for managing Pebblehost Minecraft servers directly from Claude Desktop or any MCP-compatible client.

✨ Features

• 📊 Server Status - Real-time CPU, RAM, disk usage, and uptime monitoring

• 🎮 Server Control - Start, stop, restart, and kill server processes

• 💬 Console Commands - Send Minecraft commands directly (say, kick, whitelist, etc.)

• 📁 File Management - Read, write, and manage server configuration files

• 💾 Backup Management - List and create server backups

• 🔐 Secure - API key-based authentication with Pebblehost's official API

Related MCP server: Minecraft MCP Server

📋 Prerequisites

• Node.js 16.x or higher

• Claude Desktop or any MCP-compatible client

• Pebblehost Account with an active Minecraft server

• Pebblehost API Credentials (API key and Server ID)

🚀 Quick Start

TODO: Package not yet published to npm. For now, install from source (see Installation below).

# TODO: Will be available via npm after publishing
# npm install -g pebblehost-mcp

# For now, install from source
git clone https://github.com/bop-del/pebblehost-mcp.git
cd pebblehost-mcp
npm install
npm run build

Configure Claude Desktop with your Pebblehost credentials and start managing your server through natural conversation.

📦 Installation

Step 1: Obtain Pebblehost Credentials

Get Your API Key

1. Log in to Pebblehost Panel

2. Navigate to Account → API Credentials

3. Click Create API Key

4. Copy the generated key (save it securely - you won't see it again)

Get Your Server ID

1. Open your Minecraft server in the Pebblehost Panel

2. Check the URL: panel.pebblehost.com/server/XXXXXXXX

3. The XXXXXXXX part is your Server ID

Step 2: Install the Package

Option A: Install from npm (when published)

npm install -g pebblehost-mcp

Option B: Install from source

git clone https://github.com/bop-del/pebblehost-mcp.git
cd pebblehost-mcp
npm install
npm run build

Step 3: Configure Claude Desktop

Open your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Add the server configuration:

{
  "mcpServers": {
    "pebblehost": {
      "command": "node",
      "args": ["/absolute/path/to/pebblehost-mcp/dist/index.js"],
      "env": {
        "PEBBLEHOST_API_KEY": "your_api_key_here",
        "PEBBLEHOST_SERVER_ID": "your_server_id_here"
      }
    }
  }
}

Important Notes:

• Replace /absolute/path/to/pebblehost-mcp with the actual path

• If installed globally via npm, the path will be in your global node_modules (find with npm root -g)

• Use forward slashes / even on Windows for JSON paths

• Never commit your API key to version control

Step 4: Restart Claude Desktop

Completely quit Claude Desktop and restart it to load the MCP server.

💡 Usage

Once configured, interact with your Minecraft server through natural language in Claude Desktop:

Check Server Status

English:

"What's the status of my Minecraft server?" "How much RAM is the server using?"

German:

"Wie ist der Status vom Minecraft Server?" "Wie viel RAM nutzt der Server?"

View Configuration Files

English:

"Show me the server.properties file" "What's in the whitelist.json?"

German:

"Zeig mir die server.properties" "Was steht in der whitelist.json?"

Modify Server Settings

English:

"Set spawn-protection to 0 in server.properties" "Change the difficulty to hard"

German:

"Setz spawn-protection auf 0 in server.properties" "Ändere die Schwierigkeit auf hard"

Manage Players

English:

"Kick player MaxMustermann with message 'Please don't grief!'" "Add Felix_2024 to the whitelist" "Send a message to all players: Server restarting in 5 minutes"

German:

"Kick den Spieler MaxMustermann mit der Nachricht 'Bitte nicht grieven!'" "Füg Felix_2024 zur Whitelist hinzu" "Sende eine Nachricht an alle Spieler: Server restart in 5 Minuten"

Server Control

English:

"Restart the server" "Stop the server gracefully"

German:

"Server neu starten" "Server ordentlich stoppen"

Backup Management

English:

"List all available backups" "Create a new backup before I update the plugins"

German:

"Zeig mir alle Backups" "Erstell ein Backup bevor ich die Plugins update"

🛠️ Available Tools

🔧 How It Works

This MCP server acts as a bridge between Claude Desktop and the Pebblehost API:

1. Authentication: Uses your API key to authenticate with Pebblehost

2. Server Operations: Translates natural language requests into Pebblehost API calls

3. Response Formatting: Presents API responses in a human-readable format

4. Error Handling: Provides clear error messages and troubleshooting guidance

The server implements the Model Context Protocol specification, allowing Claude to:

• Discover available tools automatically

• Execute server operations based on conversation context

• Chain multiple operations to complete complex tasks

🐛 Troubleshooting

"API error 401: Unauthorized"

Cause: Invalid or expired API key Solution: Generate a new API key in the Pebblehost Panel under Account → API Credentials and update your configuration.

"API error 404: Not Found"

Cause: Incorrect Server ID Solution: Check the Server ID in the Pebblehost Panel URL when viewing your server: panel.pebblehost.com/server/XXXXXXXX

Server Commands Not Executing

Cause: Server is offline or suspended Solution: Verify the server is running in the Pebblehost Panel and not suspended due to billing issues.

MCP Server Not Appearing in Claude

Cause: Configuration error or Claude Desktop not restarted Solution:

1. Verify the JSON syntax in claude_desktop_config.json

2. Check that the path to index.js is absolute and correct

3. Completely quit and restart Claude Desktop (not just close the window)

Permission Denied Errors

Cause: API key lacks necessary permissions Solution: Regenerate API key ensuring it has full server management permissions.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development guidelines and setup instructions.

🔮 Future Work

• Support for multiple servers in a single MCP instance

• Plugin management tools

• Advanced backup scheduling and automation

• Server performance analytics and recommendations

• Integration with more Pebblehost features (billing, support tickets)

📄 License

MIT License - see LICENSE for details.

🔗 Links

• Pebblehost - Minecraft server hosting

• Pebblehost API Documentation

• Model Context Protocol - MCP specification

• Claude Desktop - MCP-compatible AI client

Note: This is an unofficial community project and is not affiliated with or endorsed by Pebblehost. Use at your own risk and always maintain backups of your server data.