# Pebblehost Minecraft MCP Server

[![npm version](https://img.shields.io/npm/v/pebblehost-mcp.svg)](https://www.npmjs.com/package/pebblehost-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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](https://panel.pebblehost.com/)
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:

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](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](LICENSE) for details.

## 🔗 Links

- [Pebblehost](https://pebblehost.com/) - Minecraft server hosting
- [Pebblehost API Documentation](https://api.pebblehost.com/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
- [Claude Desktop](https://claude.ai/download) - 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.