minecraftmcp (Aguara Guazu)

MinecraftMCP

一个Minecraft Paper插件，通过HTTP实现模型上下文协议（MCP），使Claude Desktop等AI助手能够安全地管理您的Minecraft服务器。

概述

MinecraftMCP提供 基于HTTP的JSON-RPC 2.0 模型上下文协议的实现，允许AI助手通过标准化的界面与您的Minecraft服务器进行交互。该插件通过六个专用工具提供对服务器管理功能的安全、受控访问。

主要特点

• 仅支持HTTP的MCP实现：通过HTTP协议清理JSON-RPC 2.0
• 安全认证：具有会话管理功能的基于API密钥的身份验证
• 实时通信：实时更新的服务器发送事件（SSE）
• 指挥安全：全面的命令白名单和验证
• 速率限制：可配置的请求限制和滥用保护
• 六大核心工具：通过专门的MCP工具完成服务器管理

需求

• 纸张服务器：1.21.4或更高版本（需要纸张特定功能）
• Java：21或更晚
• 依赖项：杰克逊（2.15.2），码头（11.0.19）-通过maven shade包含汽车

安装

1. 从发行版下载插件JAR
2. 放置在您的服务器中 plugins/ 目录
3. 重新启动服务器
4. 通过编辑配置插件 plugins/MinecraftMCP/config.yml
5. 在配置中设置安全的API密钥
6. 重新启动服务器以应用配置

配置

该插件在以下位置创建了一个全面的配置文件 plugins/MinecraftMCP/config.yml:

# MinecraftMCP Configuration

# MCP Server settings
mcp-server:
  enabled: true
  transport: http  # HTTP-only transport
  http:
    port: 25575              # HTTP port for MCP API
    endpoint: "/mcp"         # API endpoint path
    sse-enabled: true        # Enable Server-Sent Events
    max-connections: 5       # Maximum SSE connections
    cors:
      enabled: false         # Enable CORS for web clients
      allowed-origins: "*"   # CORS allowed origins
    access-logging: false    # Log HTTP requests

# Security settings
security:
  authentication:
    api-key-enabled: true
    api-key: "change-this-to-a-secure-value"  # CHANGE THIS!
    localhost-only: true                      # Restrict to localhost
    session-timeout: 30                       # Session timeout (minutes)
  
  command-whitelist:
    enabled: true
    allowed-commands:        # Only these commands are allowed
      - "list"
      - "say"
      - "tp"
      - "kick"
      - "ban"
      - "pardon"
      - "op"
      - "deop"
      - "gamemode"
      - "time"
      - "weather"
      - "difficulty"
  
  rate-limiting:
    enabled: true
    commands-per-minute: 30   # Request rate limit
    max-auth-attempts: 5      # Failed auth attempts before ban
    temp-ban-duration: 15     # Temporary ban duration (minutes)

# Debug settings
debug:
  enabled: false
  log-level: INFO

# Feature toggles
features:
  player-tracking: true
  world-manipulation: true
  inventory-manipulation: true

# MCP Capabilities
capabilities:
  tools: true      # Enable MCP tools
  resources: true  # Enable MCP resources
  prompts: true    # Enable MCP prompts
  logging: true    # Enable MCP logging

MCP协议实现

建筑

┌─────────────────┐    HTTP/JSON-RPC 2.0    ┌─────────────────┐
│  Claude Desktop │◄─────────────────────────► MinecraftMCP    │
│  (MCP Client)   │                          │  Paper Plugin   │
└─────────────────┘                          └─────────────────┘
                                                      │
                                                      ▼
                                             ┌─────────────────┐
                                             │ Minecraft Paper │
                                             │     Server      │
                                             └─────────────────┘

HTTP端点

MCP方法

可用工具

MinecraftMCP为服务器管理提供了六种专用工具：

1. minecraft_execute_command

执行带有安全验证的服务器命令。

参数：

• command （string，必填）：要执行的Minecraft命令

例子：

{
  "name": "minecraft_execute_command",
  "arguments": {
    "command": "say Hello from Claude!"
  }
}

2. minecraft_server_status

获取全面的服务器状态信息。

参数： 无

退货： 服务器指标包括TPS、内存使用率、玩家数量和正常运行时间。

3. minecraft_server_logs

检索和筛选服务器日志条目。

参数：

• limit （整数，可选）：最大日志条目数（默认值：100）
• level （字符串，可选）：日志级别筛选器（信息、警告、错误）
• search （字符串，可选）：搜索词筛选器
• fromTime （字符串，可选）：ISO时间戳过滤器

4. minecraft_player_list

获取有关在线玩家的详细信息。

参数： 无

退货： 包含位置、健康状况、游戏模式和连接信息的玩家列表。

5. minecraft_manage_player

执行玩家管理操作。

参数：

• action （字符串，必填）：以下选项之一：踢、禁赛、解封、操作、脱欧、传送、传送到玩家、游戏模式
• player （字符串，必填）：目标玩家名称
• reason （字符串，可选）：踢/封的原因
• duration （整数，可选）：禁止持续时间（分钟）
• world, x, y, z （可选）：电传坐标
• target_player （字符串，可选）：teleport_to_player的目标
• gamemode （字符串，可选）：游戏模式动作的游戏模式

例子：

{
  "name": "minecraft_manage_player",
  "arguments": {
    "action": "teleport",
    "player": "Steve",
    "world": "world",
    "x": 100,
    "y": 64,
    "z": 200
  }
}

6. minecraft_world_info

检索详细的世界信息。

参数：

• world （字符串，可选）：特定世界名称
• includeChunks （布尔值，可选）：包括块信息

Claude桌面集成

重要提示： 这个项目是 纸张插件 它运行一个嵌入式HTTP服务器，而不是一个标准的MCP服务器，后者可以使用典型的 command/args 配置。

架构概述

MinecraftMCP的工作方式与标准MCP服务器不同：

• 标准MCP服务器 是Claude Desktop使用启动的独立可执行文件 command 和 args
• MinecraftMCP 是一个在Minecraft服务器内运行的Paper插件，通过HTTP公开MCP功能

集成选项

选项1:HTTP API访问

虽然与Claude Desktop的MCP集成不直接兼容，但您可以使用HTTP请求与服务器交互：

# Example: Get server status
curl -X POST http://localhost:25575/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_server_status",
      "arguments": {}
    }
  }'

方案2:MCP大桥（未来发展）

要实现真正的Claude Desktop集成，您需要：

1. MCP网桥应用：一个独立的程序，它：

- 实现标准MCP协议（stdio/命令接口） - 将请求转发到MinecraftMCP的HTTP API - 在MCP和HTTP协议之间进行转换

当前限制

• 没有直接的Claude Desktop MCP集成 -需要HTTP API调用或网桥开发
• 插件依赖性 -必须在Paper Minecraft服务器内运行
• 服务器特定 -绑定到特定的Minecraft服务器实例

入门指南

1. 在Paper服务器上安装插件
2. 配置API密钥和安全设置
3. 直接使用HTTP API或开发/等待MCP桥
4. 通过HTTP请求访问服务器管理

命令

该插件添加了以下游戏内命令：

• /mcp status -检查MCP服务器状态
• /mcp reload -重新加载配置（需要操作）
• /mcp start -启动MCP服务器（需要操作）
• /mcp stop -停止MCP服务器（需要操作）
• /mcp help -显示帮助信息

安全

身份验证流程

1. 客户端发送请求 X-API-Key 头球
2. 插件根据配置验证API密钥
3. 使用UUID和超时创建的会话
4. 根据会话和速率限制验证请求

安全功能

• API密钥验证：所有请求都需要
• 命令白名单：只允许预先批准的命令
• 速率限制：可配置的请求限制
• 会话管理：基于时间的会话过期
• 本地主机限制：可选的仅限本地主机访问
• 审计日志：全面的请求/响应日志记录

安全最佳实践

1. 更改默认的API密钥 具有强大而独特的价值
2. 启用命令白名单 并查看允许的命令
3. 仅使用本地主机 用于开发/测试
4. 设置HTTPS 通过反向代理进行生产
5. 监控日志 可疑活动
6. 定期更新 到最新插件版本

发展

从源头构建

git clone https://github.com/aguara-guazu/MinecraftMCP.git
cd MinecraftMCP
mvn clean package

编译后的JAR将位于 target/ 目录。

测试API

使用curl直接测试MCP协议：

# Initialize connection
curl -X POST http://localhost:25575/mcp \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: your-api-key" \\
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {"name": "test", "version": "1.0"}
    }
  }'

# List tools
curl -X POST http://localhost:25575/mcp \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: your-api-key" \\
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

# Execute command
curl -X POST http://localhost:25575/mcp \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: your-api-key" \\
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "minecraft_execute_command",
      "arguments": {"command": "list"}
    }
  }'

MCP响应格式

所有工具均返回MCP标准响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Tool response message here"
      }
    ]
  }
}

错误响应遵循JSON-RPC 2.0：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

故障排除

常见问题

插件未启动：

• 检查是否安装了Java 21+
• 验证纸张1.21.4+兼容性
• 查看服务器日志以了解依赖关系问题

身份验证失败：

• 验证API密钥是否与配置匹配
• 检查 localhost-only 设置是否远程连接
• 确保不超过速率限制

命令被拒绝：

• 查看配置中的命令白名单
• 检查命令是否需要额外权限
• 验证命令语法和参数

连接问题：

• 确认端口25575可用
• 检查防火墙/网络限制
• 验证MCP服务器是否已启用并启动

调试模式

在config.yml中启用调试日志记录：

debug:
  enabled: true
  log-level: DEBUG

这为故障排除提供了详细的请求/响应日志。

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交更改(git commit -m 'Add amazing feature')
4. 推送到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

支持

对于问题、疑问或功能请求：

• 打开一个问题
• 查看此README中的现有文档
• 查看CLAUDE.md文件以获取开发指导

______________________________________________________________________

版本： 1.0.5\ 兼容： 论文1.21.4+，Java 21+\ 协议： MCP 2024-11-05，JSON-RPC 2.0