MCSS MCP Server

A Model Context Protocol (MCP) server for controlling Minecraft servers via the MCSS (Minecraft Server Software) API. This tool enables seamless interaction with your Minecraft servers using MCP clients like Claude Desktop.

🌟 Features

• Server Management

  • List all Minecraft servers managed by MCSS
  • Get detailed information about specific servers
  • Execute power actions (start, stop, restart, kill)
  • Execute Minecraft commands
  • View server console output in real-time
  • Update server settings (name, description, crash handling, etc.)

• Backup Management

  • List available backups
  • Create new backup configurations
  • Run backups on demand

• Scheduler Management

  • List scheduled tasks
  • Create new scheduled tasks (commands, backups, server actions)
  • Update existing tasks
  • Delete tasks
  • Run tasks on demand

📋 Prerequisites

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

🚀 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: ~/Library/Application Support/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 path to the batch file on your system

🔧 Using the MCP Tools in Claude Desktop

Once Claude Desktop is launched, the server will start automatically and you can use the following tools:

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.

edit_server(server_id, name=None, description=None, is_set_to_auto_start=None, force_save_on_stop=None, java_allocated_memory=None, keep_online=None)

Updates a specific Minecraft server's settings. The keep_online parameter controls crash handling (0=none, 1=elevated, 2=aggressive).

execute_server_action(server_id, action)

Executes a power action on a server. Valid actions: start, stop, restart, kill.

execute_server_command(server_id, command)

Executes a Minecraft command on a server.

get_server_console(server_id, lines=50)

Returns the console output of a server.

Backup Management

get_backups(server_id)

Returns a list of backups for a server.

create_backup(server_id, name, description="", compression=None)

Creates a new backup configuration.

run_backup(server_id, backup_id)

Runs a backup for a server.

Scheduler Management

get_scheduler_tasks(server_id)

Returns a list of scheduled tasks for a server.

create_scheduler_task(server_id, name, enabled=True, ...)

Creates a new scheduled task.

update_scheduler_task(server_id, task_id, name=None, ...)

Updates an existing scheduled task.

delete_scheduler_task(server_id, task_id)

Deletes a scheduled task.

run_scheduler_task(server_id, task_id)

Runs a scheduled task immediately.

📁 Project Structure

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

🤝 Contributing

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 the Model Context Protocol specification
• Claude Desktop for the MCP client implementation