What is Mc Mcp Server

mc-mcp-server is a Minecraft Bedrock AIAgent server built using Python, which integrates WebSocket and MCP-server to manage AI tools and handle interactions with large language models (LLMs). It supports two request paths: external MCP client calls and in-game chat listening.

Use cases

Use cases for mc-mcp-server include creating AI-driven NPCs in Minecraft, enabling intelligent chatbots for player interactions, and developing tools that enhance player engagement through AI-assisted gameplay.

How to use

To use mc-mcp-server, first read the project requirements document to understand the core functionalities. Then, refer to the technical architecture document for system design insights. Familiarize yourself with the WebSocket communication specifications and the MCP integration guidelines to learn how to set up and interact with the server.

Key features

Key features of mc-mcp-server include WebSocket-based communication, integration with Minecraft’s scripting API, support for external MCP clients, and the ability to trigger AI interactions through in-game chat.

Where to use

mc-mcp-server can be used in gaming environments, particularly in Minecraft Bedrock Edition, where AI interactions enhance gameplay experiences. It is suitable for developers looking to integrate AI functionalities into their Minecraft servers.

Minecraft MCP服务器文档索引

项目概述

Minecraft MCP服务器是一个集成系统，由两个核心组件组成：AIAgent(MCP-server)负责管理AI工具和处理LLM交互，以及基于WebSocket和脚本API的MC服务器负责处理游戏交互。系统支持两种请求路径：外部MCP客户端调用和游戏内聊天监听。

文档目录

1. 项目需求文档

• 项目需求描述文档 (PRD) - 详细描述项目的核心功能、请求路径、用户交互流程和验收标准

2. 技术规范文档

• 技术架构文档 - 描述系统的整体架构、核心组件和技术栈
• WebSocket通信规范 - 定义客户端与服务器之间的WebSocket通信协议和脚本API集成
• MCP集成规范 - 说明如何集成Model Context Protocol标准和两种请求路径

3. 外部参考文档

• MCP Python SDK - Model Context Protocol的Python实现参考
• Minecraft脚本API文档 - Minecraft脚本API官方文档
• MCP客户端示例 - 如何使用外部MCP客户端与服务器通信的示例

系统组件

1. AIAgent (mc-server) - 基于WebSocket和脚本API的服务器，处理游戏交互
2. MCP服务器 - 负责管理AI工具和处理LLM交互，通过MCP前端服务器实现外部MCP客户端的访问

请求路径

1. 外部MCP客户端路径 - 外部MCP客户端通过AIAgent与Minecraft交互
2. 游戏内聊天路径 - 玩家通过游戏内聊天触发AIAgent

快速入门

1. 阅读项目需求描述文档了解项目概况
2. 参考技术架构文档了解系统设计
3. 查看WebSocket通信规范了解通信协议和脚本API集成
4. 学习MCP集成规范了解LLM集成方式和请求路径

项目结构规范

mc-mcp-server/
├── server/
│   ├── __init__.py
│   ├── mc_server.py       # WebSocket服务器实现
│   ├── agent_server.py      # Agent服务器实现
│   └── utils/
│       ├── __init__.py
│       ├── auth.py        # 认证相关工具
│       ├── llm.py         # 大语言模型调用工具
│       └── logging.py     # 日志工具
│
├── resources/             # MCP资源定义
│   ├── __init__.py
│   ├── player.py
│   └── world.py
├── tools/                 # MCP工具定义
│   ├── __init__.py
│   ├── commands.py
│   └── messages.py
├── config/                # 配置文件
│   ├── default.json
│   └── production.json
├── tests/                 # 测试目录
│   ├── __init__.py
│   ├── test_mc_server.py
│   └── test_mcp_server.py
├── docs/                  # 文档目录
├── main.py                # 主入口文件
├── requirements.txt       # 依赖声明
└── README.md              # 项目说明

开发指南

1. 安装依赖:

   pip install -r requirements.txt
   

2. 设置环境变量:

   export DEEPSEEK_API_KEY=your_api_key
   

3. 启动MC服务器:

使用uv (推荐)

• 安装uv

pip install uv

• 使用uv运行

uv run main.py --full --mcp

• 调试模式（记录WebSocket数据包）

uv run main.py --full --mcp --debug

• 直接运行

python main.py --full --mcp

• 调试模式

python main.py --full --mcp --debug

4. 连接Minecraft客户端到MC服务器(默认端口8080)
5. (可选)连接外部mcp客户端(http://0.0.0.0:8000/sse)

调试与日志

服务器提供了调试模式和增强的日志功能，帮助开发者诊断和解决问题：

• 调试模式：使用 --debug 参数启动服务器，记录所有WebSocket数据包
• 日志文件：日志自动保存在 logs 目录下
  • 主服务器日志：logs/server_YYYYMMDD-HHMMSS.log
  • WebSocket数据包日志：logs/packets/packets_YYYYMMDD-HHMMSS.log

详细信息请参阅 调试模式和日志功能文档。

贡献指南

1. 遵循项目的代码风格和架构设计
2. 提交前确保代码通过测试
3. 更新相关文档以反映代码变更

版本历史

许可信息

• 本项目以MIT开源
• 其他项目许可证见LICENSES