使用说明

Minecraft MCP桥

一种使大型语言模型（LLM）能够通过模型上下文协议（MCP）与Minecraft服务器交互的系统。

概述

Minecraft MCP Bridge由三个组件组成，它们协同工作以实现LLM与Minecraft的交互：

MCP服务器 -将Minecraft操作暴露为LLM可以调用的MCP工具
网桥服务器 -WebSocket中继，在MCP服务器和Minecraft之间路由消息
Minecraft Mod -NeoForge mod，挂钩游戏事件并执行命令

┌─────────────┐         ┌──────────────┐         ┌──────────────┐
│             │  MCP    │              │  WS     │              │
│ LLM Client  │◄───────►│  MCP Server  │◄───────►│    Bridge    │
│             │         │              │         │    Server    │
└─────────────┘         └──────────────┘         └──────────────┘
                                                         │
                                                         │ WS
                                                         ▼
                                                  ┌──────────────┐
                                                  │  Minecraft   │
                                                  │     Mod      │
                                                  └──────────────┘

特性

实时事件通知：接收有关玩家加入、聊天消息、死亡等的通知
命令执行：执行Minecraft命令、发送消息、传送玩家、赠送物品
服务器查询：查询玩家信息、服务器状态和世界状态
事件过滤：订阅特定事件类型以减少噪音
安全：基于令牌的身份验证和命令白名单
韧性：具有指数回退的自动重新连接
演出：低于1000毫秒的消息转发延迟

快速开始

Docker部署（推荐）

部署MCP服务器和网桥服务器的最简单方法是使用Docker：

# 1. Copy and configure environment variables
cp .env.docker.example .env
# Edit .env with secure authentication tokens

# 2. Start services with Docker Compose
docker-compose up -d

# 3. Check service health
curl http://localhost:8081/health

# 4. View logs
docker-compose logs -f

看部署.md 了解完整的Docker部署说明和生产注意事项。

手动安装

先决条件

Node.js 18+ npm（用于MCP服务器和网桥服务器）
Java 17+ （适用于Minecraft Mod）
minecraft服务器 安装了NeoForge 1.20.1+
码头工人 （可选，用于容器化部署）

1.安装依赖项

# Install Node.js dependencies
npm install

# Build all TypeScript packages
npm run build

2.配置网桥服务器

cd packages/bridge-server
cp .env.example .env

编辑 .env 并设置您的身份验证令牌：

PORT=8080
MCP_AUTH_TOKENS=your-mcp-token-here
MINECRAFT_AUTH_TOKEN=your-minecraft-token-here

3.配置MCP服务器

cd packages/mcp-server
cp .env.example .env

编辑 .env:

BRIDGE_URL=ws://localhost:8080
AUTH_TOKEN=your-mcp-token-here

4.构建并安装Minecraft Mod

cd packages/minecraft-plugin
./gradlew build

将构建的JAR复制到您的Minecraft服务器：

cp build/libs/minecraft-mcp-bridge-*.jar /path/to/minecraft/server/mods/

5.配置Minecraft Mod

创建 config/minecraft-mcp-bridge.toml 在您的Minecraft服务器目录中：

[bridge]
url = "ws://localhost:8080"
auth_token = "your-minecraft-token-here"

[events]
enabled = ["player_join", "player_quit", "player_chat", "player_death", "block_break"]

[commands]
allowed_patterns = [
    "^say .*",
    "^tp \\w+ -?\\d+ -?\\d+ -?\\d+$",
    "^give \\w+ \\w+ \\d+$"
]

看 packages/minecraft-plugin/minecraft-mcp-bridge.toml.example 对于所有配置选项。

6.启动系统

按顺序启动每个组件：

# Terminal 1: Start Bridge Server
cd packages/bridge-server
npm start

# Terminal 2: Start MCP Server
cd packages/mcp-server
npm start

# Terminal 3: Start Minecraft Server
cd /path/to/minecraft/server
./start.sh  # or your server start script

7.连接LLM客户端

MCP服务器向LLM客户端公开以下工具：

execute_command -执行任意Minecraft命令
send_message -向玩家发送消息
teleport_player -将玩家传送到坐标
give_item -将物品赠送给玩家
get_online_players -列出在线玩家
get_player_info -获取详细的玩家信息
get_server_info -获取服务器状态
get_world_info -查询区域中的块和实体

项目结构

minecraft-mcp-bridge/
├── packages/
│   ├── shared/           # Shared TypeScript types
│   ├── mcp-server/       # MCP Server implementation
│   ├── bridge-server/    # WebSocket bridge server
│   └── minecraft-plugin/ # Minecraft NeoForge mod (Java)
├── .kiro/specs/          # Design specifications
├── PROTOCOL.md           # Message protocol documentation
└── README.md

配置

网桥服务器配置

看 packages/bridge-server/.env.example 所有可用选项。

关键设置：

PORT -WebSocket服务器端口（默认：8080）
MCP_AUTH_TOKENS -以逗号分隔的有效MCP令牌列表
MINECRAFT_AUTH_TOKEN -Minecraft Mod身份验证令牌
MESSAGE_QUEUE_SIZE -每个客户端的最大排队消息数（默认值：1000）
HEARTBEAT_INTERVAL -连接健康检查间隔（默认值：30000ms）

MCP服务器配置

看 packages/mcp-server/.env.example 所有可用选项。

关键设置：

BRIDGE_URL -网桥服务器的WebSocket URL
AUTH_TOKEN -身份验证令牌（必须与网桥服务器的MCP_AUTH_TOKENS中的令牌匹配）
RECONNECT_ATTEMPTS -最大重新连接尝试次数（默认值：5）
RECONNECT_DELAY -初始重新连接延迟（默认值：1000ms）

Minecraft Mod配置

看 packages/minecraft-plugin/minecraft-mcp-bridge.toml.example 所有可用选项。

关键设置：

bridge.url -网桥服务器的WebSocket URL
bridge.auth_token -身份验证令牌（必须与网桥服务器的MINECRAFT_AUTH_token匹配）
events.enabled -要监视的事件类型列表
commands.allowed_patterns -允许命令的正则表达式模式
security.max_command_length -最大命令长度（默认值：256）

部署

Docker部署

对于生产部署，我们建议使用Docker：

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

# Stop services
docker-compose down

看部署.md 用于：

完整的Docker部署指南
Minecraft Mod安装说明
生产安全考虑
监测和健康检查
常见问题排查

Kubernetes部署

对于Kubernetes部署，您可以使用Docker镜像作为基础。示例清单：

# See DEPLOYMENT.md for complete Kubernetes examples
apiVersion: apps/v1
kind: Deployment
metadata:
  name: bridge-server
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: bridge-server
        image: minecraft-bridge-server:latest
        ports:
        - containerPort: 8080
        - containerPort: 8081

发展

建筑

# Build all TypeScript packages
npm run build

# Build Minecraft mod
cd packages/minecraft-plugin
./gradlew build

测试

# Run all TypeScript tests
npm test

# Run tests for specific package
cd packages/bridge-server
npm test

# Run Minecraft mod tests
cd packages/minecraft-plugin
./gradlew test

测试框架

TypeScript包：使用ts-Jest进行单元测试，快速检查基于属性的测试
Java模块：JUnit用于单元测试，jqwik用于基于属性的测试

协议文件

看协议.md 有关消息协议和模式的详细文档。

安全考虑

生产部署

使用强代币：生成加密安全的随机令牌进行身份验证
启用TLS：使用 wss:// 而不是 ws:// 用于生产中的WebSocket连接
限制命令：仔细配置 allowed_patterns 只允许安全命令
网络隔离：在专用网络中运行网桥服务器，仅向MCP服务器公开
防火墙规则：限制对Minecraft服务器和网桥服务器端口的访问
监控日志：启用审核日志记录以跟踪所有命令执行

命令白名单示例

# Safe patterns - only allow specific commands
allowed_patterns = [
    "^say .*",                                    # Allow chat messages
    "^tp \\w+ -?\\d+ -?\\d+ -?\\d+$",           # Allow teleport with coordinates
    "^give \\w+ minecraft:\\w+ \\d+$",          # Allow giving items
    "^time set (day|night)$",                    # Allow time changes
    "^weather (clear|rain|thunder)$",            # Allow weather changes
    "^gamemode (survival|creative) \\w+$"        # Allow gamemode changes
]

# DANGEROUS - avoid these patterns
# ".*"                    # Allows ANY command (never use this!)
# "^op .*"                # Allows granting operator status
# "^deop .*"              # Allows removing operator status
# "^stop$"                # Allows stopping the server

故障排除

连接问题

问题：MCP服务器或Minecraft Mod无法连接到网桥服务器

解决方案:

验证网桥服务器是否正在正确的端口上运行和侦听
检查所有配置中的身份验证令牌是否匹配
确保防火墙允许在配置的端口上进行WebSocket连接
检查日志中的身份验证错误

命令执行失败

问题：命令被拒绝或无法执行

解决方案:

验证命令是否与以下命令之一匹配 allowed_patterns 在Minecraft Mod配置中
检查命令长度不超过 max_command_length
确保玩家姓名和坐标有效
查看Minecraft Mod日志以获取详细的错误消息

缺失事件

问题：未收到预期的事件通知

解决方案:

验证事件类型是否在 enabled Minecraft Mod配置中的列表
检查MCP服务器订阅筛选器（默认为所有事件）
确保Minecraft Mod已连接到网桥服务器
查看网桥服务器日志以了解消息路由

高延迟

问题：命令或事件运行缓慢

解决方案:

检查组件之间的网络延迟
减少 MESSAGE_QUEUE_SIZE 如果邮件正在备份
增加 HEARTBEAT_INTERVAL 减少开销
监控所有组件的CPU和内存使用情况

演出

该系统专为低延迟而设计：

消息转发：从源到目标小于100ms
事件吞吐量：每秒处理100+个事件
命令执行：对于简单命令，通常<50ms

贡献

看 .kiro/specs/minecraft-mcp-bridge/ 用于设计规范和实施任务。

许可证

[在此处添加您的许可证]

支持

对于问题和疑问：

检查协议.md 有关消息格式的详细信息
查看中的配置示例 .env.example 和 .toml.example 文件
检查组件日志以获取详细的错误消息

使用说明

Minecraft MCP桥

概述

特性

快速开始

Docker部署（推荐）

手动安装

先决条件

1.安装依赖项

2.配置网桥服务器

3.配置MCP服务器

4.构建并安装Minecraft Mod

5.配置Minecraft Mod

6.启动系统

7.连接LLM客户端

项目结构

配置

网桥服务器配置

MCP服务器配置

Minecraft Mod配置

部署

Docker部署

Kubernetes部署

发展

建筑

测试

测试框架

协议文件

安全考虑

生产部署

命令白名单示例

故障排除

连接问题

命令执行失败

缺失事件

高延迟

演出

贡献

许可证

支持

相关 MCP

Minecraft MCP服务器

GraphQL API交互服务

GraphQL协议服务器

LLM交互工具

JSON处理工具

Minecraft远程控制工具