MCSS MCP Server

MCSS MCP 服务

一个通过 MCSS（Minecraft Server Software）API 控制 Minecraft 服务的模型上下文协议（MCP）服务。此工具可让你使用 Claude Desktop 等 MCP 客户端与 Minecraft 服务无缝交互。

🌟 功能

• 服务管理

  • 列出 MCSS 管理的所有 Minecraft 服务
  • 获取特定服务的详细信息
  • 执行电源操作（启动、停止、重启、强制终止）
  • 执行 Minecraft 命令
  • 实时查看服务控制台输出
  • 更新服务设置（名称、描述、崩溃处理等）

• 备份管理

  • 列出可用备份
  • 创建新的备份配置
  • 按需运行备份

• 计划任务管理

  • 列出计划任务
  • 创建新的计划任务（命令、备份、服务操作）
  • 更新现有任务
  • 删除任务
  • 按需运行任务

📋 前提条件

• Python 3.10 或更高版本
• 已启用 Web API 的 MCSS（Minecraft Server Software）
• MCSS Web API 的 API 密钥
• Claude Desktop（用于 MCP 客户端功能）

🚀 快速开始

安装

1. 克隆此仓库：

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

2. 创建并激活虚拟环境：

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

3. 安装所需依赖：

   pip install mcp[cli] httpx python-dotenv
   

配置

1. 在项目根目录中创建 .env 文件：

   MCSS_HOST=your_mcss_host_ip
   MCSS_PORT=25560
   MCSS_API_KEY=your_mcss_api_key
   

2. 配置 Claude Desktop 以使用此 MCP 服务：

   • 打开 Claude Desktop 配置文件：
     • Windows：%AppData%\Claude\claude_desktop_config.json
     • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • 添加以下配置：

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

   • 将路径替换为系统中批处理文件的实际路径

🔧 在 Claude Desktop 中使用 MCP 工具

启动 Claude Desktop 后，服务将自动启动，你可以使用以下工具：

服务管理

get_servers()

返回 MCSS 管理的所有 Minecraft 服务列表。

get_server_details(server_id)

返回特定服务的详细信息。

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)

更新特定 Minecraft 服务的设置。keep_online 参数控制崩溃处理（0=无，1=增强，2=激进）。

execute_server_action(server_id, action)

对服务执行电源操作。有效操作：start、stop、restart、kill。

execute_server_command(server_id, command)

在服务上执行 Minecraft 命令。

get_server_console(server_id, lines=50)

返回服务的控制台输出。

备份管理

get_backups(server_id)

返回服务的备份列表。

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

创建新的备份配置。

run_backup(server_id, backup_id)

为服务运行备份。

计划任务管理

get_scheduler_tasks(server_id)

返回服务的计划任务列表。

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

创建新的计划任务。

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

更新现有计划任务。

delete_scheduler_task(server_id, task_id)

删除计划任务。

run_scheduler_task(server_id, task_id)

立即运行计划任务。

📁 项目结构

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

🤝 参与贡献

欢迎贡献！欢迎随时提交 Pull Request。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🙏 致谢

• MCSS 提供 Minecraft 服务管理软件
• MCP 提供模型上下文协议规范
• Claude Desktop 提供 MCP 客户端实现