Mcss MCP Server

🚀 MCSS MCP Server

An MCP (Model Context Protocol) server that controls Minecraft servers via the MCSS (Minecraft Server Software) API. This tool allows seamless interaction with your Minecraft servers using MCP clients like Claude Desktop.

🚀 Quick Start

Installation

1. Clone this repository:

git clone https://github.com/largeorbitalobject/mcss-mcp-server.git
cd mcss-mcp-server

2. Create and activate a virtual environment:

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

3. Install the required dependencies:

pip install mcp[cli] httpx python-dotenv

Configuration

1. Create a .env file in the project root directory:

MCSS_HOST=your_mcss_host_ip
MCSS_PORT=25560
MCSS_API_KEY=your_mcss_api_key

2. Configure Claude Desktop to use this MCP server:

• Open your Claude Desktop configuration file:
  • Windows: %AppData%\Claude\claude_desktop_config.json%
  • macOS: %home%/.config/Claude/claude_desktop_config.json%
• Add the following configuration:

{
  "mcpServers": {
    "mcss-control": {
      "command": "C:\\path\\to\\mcss-mcp-server\\run_mcss_mcp.bat",
      "args": []
    }
  }
}

• Replace the path with the actual batch file path on your system.

✨ Features

Server Management

• List Servers: List all Minecraft servers managed by MCSS.
• Get Server Details: Retrieve detailed information about a specific server.
• Power Operations: Perform power operations (start, stop, restart, terminate).
• Execute Commands: Execute Minecraft commands.
• View Console Output: View the server console output in real-time.
• Update Settings: Update server settings (name, description, crash handling, etc.).

Backup Management

• List Backups: List available backups.
• Create Backup Config: Create a new backup configuration.
• Run Backup: Run a backup when needed.

Scheduler Management

• List Scheduled Tasks: List scheduled tasks.
• Create Scheduled Task: Create a new scheduled task (command, backup, server operation).
• Update Task: Update an existing task.
• Delete Task: Delete a task.
• Run Task: Run a task when needed.

📋 Prerequisites

• Python 3.10 or higher
• MCSS (Minecraft Server Software) with Web API enabled
• API key for the MCSS Web API
• Claude Desktop (for MCP client functionality)

💻 Usage Examples

Server Management

get_servers()

Returns a list of all Minecraft servers managed by MCSS.

get_server_details(server_id)

Returns detailed information about a specific server.

set_server_settings(server_id, settings)

Updates the settings of the specified server.

restart_server(server_id)

Restarts the specified server.

shutdown_server(server_id)

Shuts down the specified server.

Backup Management

create_backup(server_id)

Creates a backup for the specified server.

delete_backup(server_id, backup_id)

Deletes a specific backup of the specified server.

get_backups(server_id)

Returns a list of all backups for the specified server.

Scheduler Management

create_schedule(server_id, schedule)

Creates a new scheduled task for the specified server.

delete_schedule(server_id, schedule_id)

Deletes a specific scheduled task of the specified server.

get_schedules(server_id)

Returns a list of all scheduled tasks for the specified server.

run_schedule(server_id, schedule_id)

Runs a specific scheduled task of the specified server immediately.

📁 Project Structure

mcss-mcp-server/
├── mcss_mcp/                # Main package
│   ├── __init__.py          # Package initialization
│   └── server.py            # MCP server implementation
├── main.py                  # Entry script
├── run_mcss_mcp.bat         # Batch script to run the server
├── .env                     # Environment variables (not in the code repository)
└── README.md                # This file

🤝 Contribution

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• MCSS for providing the Minecraft server management software
• MCP for providing the Model Context Protocol specification
• Claude Desktop for providing the MCP client implementation