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

📋 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

Tool	Description
get_server_status	Retrieve server status (state, CPU, RAM, disk, uptime)
get_server_info	Get detailed server information and configuration
send_command	Send a Minecraft console command to the server
power_action	Execute power actions (start, stop, restart, kill)
list_files	List files and directories in a server path
read_file	Read the contents of a server file
write_file	Write content to a server file
delete_file	Delete a file from the server
create_directory	Create a new directory on the server
rename_file	Rename or move a file/directory
list_backups	List all available server backups
create_backup	Create a new server backup

🔧 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.