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).```bash
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)**```bash
npm install -g pebblehost-mcp
Option B: Install from source```bash
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:```json
{
"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:
- Authentication: Uses your API key to authenticate with Pebblehost
- Server Operations: Translates natural language requests into Pebblehost API calls
- Response Formatting: Presents API responses in a human-readable format
- 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.