Minecraft Server MCP

🎮 AI-Powered Minecraft Server Management via Model Context Protocol

English | 中文

Quick Install

pip install minecraft-server-mcp

📦 PyPI Package • 📖 Documentation • 🐛 Issues

📖 English Documentation

Overview

Minecraft Server MCP is a Model Context Protocol (MCP) server implementation that enables AI assistants to interact with and manage Minecraft servers through a standardized interface. This project bridges AI capabilities with Minecraft server administration, making it easy to:

• 🎮 Monitor server status and performance in real-time

• 👥 Manage players and query online status

• 🔌 View and manage installed plugins

• 📝 Execute server commands programmatically

• 📊 Access and filter server logs, errors, and warnings

• 🔗 Connect to multiple Minecraft servers simultaneously

Architecture

The project consists of two main components:

1. Python MCP Server (src/smc/) - Implements the Model Context Protocol, providing a standardized interface for AI assistants

2. Java Minecraft Plugin (plugin/) - Runs inside your Minecraft server, exposing an HTTP API for server management

Table of Contents

• Installation

  • Prerequisites

  • Python MCP Server Setup

  • Minecraft Plugin Setup

• Quick Start

• Configuration

• Core Features

  • Connection Management

  • Server Monitoring

  • Player Management

  • Log Analysis

  • Command Execution

• Available Tools

• Development

• Contributing

• License

Installation

Prerequisites

• Python: 3.12 or higher

• Minecraft Server: Spigot/Paper 1.8.9-1.21.x (excluding 1.17)

• Java: JDK 8 or higher (for building the plugin)

• Maven: For building the Minecraft plugin

Python MCP Server Setup

We recommend using uv for Python dependency management.

1. Clone the repository:

git clone https://github.com/Ver-zhzh/MCP-For-Minecraft-Server.git
cd MCP-For-Minecraft-Server

2. Install dependencies:

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

3. Verify installation:

# Using uv
uv run python -m smc

# Or using pip
python -m smc

Minecraft Plugin Setup

1. Build the plugin:

cd plugin
mvn clean package

2. Install the plugin:

Copy the generated JAR file to your Minecraft server's plugins folder:

cp target/SMC-Plugin.jar /path/to/your/minecraft/server/plugins/

3. Configure the plugin:

Edit plugins/SMC-Plugin/config.yml in your Minecraft server directory:

# HTTP API Configuration
http:
  port: 8080
  host: "0.0.0.0"

# Security
security:
  api_key: "your-secure-api-key-here"
  
# Logging
logging:
  level: INFO

4. Restart your Minecraft server to load the plugin.

Quick Start

1. Start the Minecraft Server

Ensure your Minecraft server is running with the SMC Plugin installed.

2. Configure MCP Server

Set environment variables or create a configuration file:

export MINECRAFT_LOG_LEVEL=INFO
export MINECRAFT_LOG_FILE=smc-server.log

3. Run the MCP Server

# Using uv
uv run python -m smc

# Or using pip
python -m smc

4. Connect to Your Minecraft Server

Use the MCP client to connect:

{
  "tool": "connect",
  "arguments": {
    "url": "http://localhost:8080",
    "api_key": "your-secure-api-key-here",
    "timeout": 10
  }
}

5. Query Server Status

{
  "tool": "status",
  "arguments": {
    "api_key": "your-secure-api-key-here"
  }
}

Configuration

Environment Variables

Plugin Configuration

Located at plugins/SMC-Plugin/config.yml:

http:
  port: 8080              # HTTP API port
  host: "0.0.0.0"         # Bind address

security:
  api_key: "your-key"     # API authentication key

logging:
  level: INFO             # Plugin log level
  max_entries: 1000       # Maximum log entries to keep

Core Features

Connection Management

Connect to multiple Minecraft servers using unique API keys:

• connect - Establish connection to a server

• disconnect - Close connection to a server

• list_servers - View all active connections

Server Monitoring

Get real-time server information:

• status - Server version, online status, and basic info

• plugins - List installed plugins with versions and authors

Player Management

Track and manage players:

• player_list - Get online players with UUID and ping information

Log Analysis

Access comprehensive server logs:

• get_logs - Retrieve logs with time-based filtering

• get_errors - Filter error-level logs by plugin

• get_warnings - Filter warning-level logs

Command Execution

Execute server commands programmatically:

• send_command - Execute single or multiple commands

• get_commands - List all available server commands

Available Tools

Development

Running Tests

# Python tests
uv run pytest

# Java plugin tests
cd plugin
mvn test

Project Structure

minecraft-server-mcp/
├── src/smc/                    # Python MCP server
│   ├── __init__.py
│   ├── server.py               # Main MCP server
│   ├── client.py               # HTTP client for plugin API
│   ├── tools.py                # MCP tool implementations
│   ├── config.py               # Configuration management
│   └── connection_manager.py   # Multi-server connection manager
├── plugin/                     # Java Minecraft plugin
│   ├── src/main/java/
│   │   └── com/smc/            # Plugin source code
│   ├── src/main/resources/
│   │   └── plugin.yml          # Plugin metadata
│   └── pom.xml                 # Maven configuration
├── .python-version             # Python version (3.12)
├── uv.lock                     # Dependency lock file
└── README.md                   # This file

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

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

Related MCP server: MCSManager MCP Server

📖 中文文档

快速安装

pip install minecraft-server-mcp

📦 PyPI 包 • 📖 文档 • 🐛 问题反馈

概述

Minecraft Server MCP 是一个 Model Context Protocol (MCP) 服务器实现，使 AI 助手能够通过标准化接口与 Minecraft 服务器进行交互和管理。该项目将 AI 能力与 Minecraft 服务器管理相结合，轻松实现：

• 🎮 实时监控服务器状态和性能

• 👥 管理玩家并查询在线状态

• 🔌 查看和管理已安装的插件

• 📝 程序化执行服务器命令

• 📊 访问和过滤服务器日志、错误和警告

• 🔗 同时连接多个 Minecraft 服务器

架构

项目由两个主要组件组成:

1. Python MCP 服务器 (src/smc/) - 实现 Model Context Protocol，为 AI 助手提供标准化接口

2. Java Minecraft 插件 (plugin/) - 在 Minecraft 服务器中运行，提供 HTTP API 用于服务器管理

目录

• 安装

  • 前置要求

  • Python MCP 服务器设置

  • Minecraft 插件设置

• 快速开始

• 配置

• 核心功能

  • 连接管理

  • 服务器监控

  • 玩家管理

  • 日志分析

  • 命令执行

• 可用工具

• 开发

• 贡献

• 许可证

安装

前置要求

• Python: 3.12 或更高版本

• Minecraft 服务器: Spigot/Paper 1.8.9-1.21.x（不支持 1.17）

• Java: JDK 8 或更高版本（用于构建插件）

• Maven: 用于构建 Minecraft 插件

Python MCP 服务器设置

我们推荐使用 uv 进行 Python 依赖管理。

1. 克隆仓库:

git clone https://github.com/Ver-zhzh/MCP-For-Minecraft-Server.git
cd MCP-For-Minecraft-Server

2. 安装依赖:

# 使用 uv（推荐）
uv sync

# 或使用 pip
pip install -e .

3. 验证安装:

# 使用 uv
uv run python -m smc

# 或使用 pip
python -m smc

Minecraft 插件设置

1. 构建插件:

cd plugin
mvn clean package

2. 安装插件:

将生成的 JAR 文件复制到 Minecraft 服务器的 plugins 文件夹:

cp target/SMC-Plugin.jar /path/to/your/minecraft/server/plugins/

3. 配置插件:

在 Minecraft 服务器目录中编辑 plugins/SMC-Plugin/config.yml:

# HTTP API 配置
http:
  port: 8080
  host: "0.0.0.0"

# 安全设置
security:
  api_key: "your-secure-api-key-here"
  
# 日志设置
logging:
  level: INFO

4. 重启 Minecraft 服务器 以加载插件。

快速开始

1. 启动 Minecraft 服务器

确保您的 Minecraft 服务器正在运行且已安装 SMC 插件。

2. 配置 MCP 服务器

设置环境变量或创建配置文件:

export MINECRAFT_LOG_LEVEL=INFO
export MINECRAFT_LOG_FILE=smc-server.log

3. 运行 MCP 服务器

# 使用 uv
uv run python -m smc

# 或使用 pip
python -m smc

4. 连接到您的 Minecraft 服务器

使用 MCP 客户端连接:

{
  "tool": "connect",
  "arguments": {
    "url": "http://localhost:8080",
    "api_key": "your-secure-api-key-here",
    "timeout": 10
  }
}

5. 查询服务器状态

{
  "tool": "status",
  "arguments": {
    "api_key": "your-secure-api-key-here"
  }
}

配置

环境变量

插件配置

位于 plugins/SMC-Plugin/config.yml:

http:
  port: 8080              # HTTP API 端口
  host: "0.0.0.0"         # 绑定地址

security:
  api_key: "your-key"     # API 认证密钥

logging:
  level: INFO             # 插件日志级别
  max_entries: 1000       # 保留的最大日志条目数

核心功能

连接管理

使用唯一的 API 密钥连接到多个 Minecraft 服务器:

• connect - 建立到服务器的连接

• disconnect - 关闭到服务器的连接

• list_servers - 查看所有活动连接

服务器监控

获取实时服务器信息:

• status - 服务器版本、在线状态和基本信息

• plugins - 列出已安装的插件及版本和作者

玩家管理

跟踪和管理玩家:

• player_list - 获取在线玩家及其 UUID 和延迟信息

日志分析

访问全面的服务器日志:

• get_logs - 使用基于时间的过滤检索日志

• get_errors - 按插件过滤错误级别日志

• get_warnings - 过滤警告级别日志

命令执行

程序化执行服务器命令:

• send_command - 执行单个或多个命令

• get_commands - 列出所有可用的服务器命令

可用工具

开发

运行测试

# Python 测试
uv run pytest

# Java 插件测试
cd plugin
mvn test

项目结构

minecraft-server-mcp/
├── src/smc/                    # Python MCP 服务器
│   ├── __init__.py
│   ├── server.py               # 主 MCP 服务器
│   ├── client.py               # 插件 API 的 HTTP 客户端
│   ├── tools.py                # MCP 工具实现
│   ├── config.py               # 配置管理
│   └── connection_manager.py   # 多服务器连接管理器
├── plugin/                     # Java Minecraft 插件
│   ├── src/main/java/
│   │   └── com/smc/            # 插件源代码
│   ├── src/main/resources/
│   │   └── plugin.yml          # 插件元数据
│   └── pom.xml                 # Maven 配置
├── .python-version             # Python 版本 (3.12)
├── uv.lock                     # 依赖锁定文件
└── README.md                   # 本文件

贡献

欢迎贡献！请遵循以下指南:

1. Fork 本仓库

2. 创建功能分支 (git checkout -b feature/amazing-feature)

3. 提交您的更改 (git commit -m 'Add amazing feature')

4. 推送到分支 (git push origin feature/amazing-feature)

5. 打开 Pull Request

许可证

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

🌟 Star History

If you find this project helpful, please consider giving it a star! ⭐

如果您觉得这个项目有帮助，请考虑给它一个星标！⭐