Maicraft

基于 mineflayer 构建的 Minecraft MCP Server。

主要用于和Amaidesu项目配合（maicraft插件现已独立成新的仓库MaiM-with-u/Maicraft），让MaiBot游玩Minecraft游戏。

当然，也可以像普通MCP Server一样使用本项目。

部分高级动作的实现参考自 mineland

安装

请提前配置好minecraft服务器，无论是minecraft客户端直接开局域网游戏，或是minecraft服务器，都支持，版本会自动检测。

推荐的游戏版本：1.20.4

1.21.4也支持，但mineflayer在此版本有些问题，更高的版本可能会有问题，1.21.8目前测出来是不支持的。

方法一：使用npx执行npm包来配置

{
  "mcpServers": {
    "maicraft": {
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "maicraft@latest",
        "--host","127.0.0.1",
        "--port","25565",
        "--username","Mai",
         "--auth", "offline"
      ]
    }
  }
}

这里的@latest表示使用最新版本，你也可以替换为其他版本。

方法二：提前全局下载

你可以提前全局安装maicraft，然后再按照方法一进行配置，这样启动时会使用你全局下载的maicraft而不是npx下载的，这样可以避免调用它的时候过慢（因为需要临时下载），缺点是你需要手动升级。

npm install maicraft -g

方法三：本地构建

当你的网络不太好，可以使用本地构建。首先clone本地项目

git clone git@github.com:ChangingSelf/maicraft-mcp-server.git
cd maicraft-mcp-server
pnpm install
pnpm run build

然后配置为：

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "/path/to/maicraft-mcp-server/dist/main.js",
        "--host",
        "localhost",
        "--port",
        "25565",
        "--username",
        "EvilMai",
      ]
    }
  }
}

如果你不想每次都 pnpm run build，也可以直接指定为 main.ts，只不过需要tsx来执行

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": [
        "tsx"
        "/path/to/maicraft-mcp-server/src/main.ts",
        "--host",
        "localhost",
        "--port",
        "25565",
        "--username",
        "EvilMai",
      ]
    }
  }
}

配置

Maicraft 支持两种配置方式：命令行参数和配置文件。

方式一：命令行参数（推荐）

最简单的方式是直接在启动时使用命令行参数，无需创建配置文件：

# 基本连接参数
--host <地址>           # Minecraft 服务器地址（默认：127.0.0.1）
--port <端口>           # 服务器端口（默认：25565）
--username <用户名>     # 机器人用户名
--auth <认证方式>       # offline | microsoft | mojang（默认：offline）

# 日志配置
--log-level <级别>      # DEBUG | INFO | WARN | ERROR（默认：INFO）

# 事件过滤
--events-disabled <事件列表>  # 要禁用的事件，用逗号分隔

快速开始示例：

# 连接本地服务器
npx -y maicraft --host 127.0.0.1 --username MyBot

# 连接远程服务器并启用调试日志
npx -y maicraft --host mc.example.com --port 25565 --username Bot --log-level DEBUG

# 禁用聊天事件减少噪音
npx -y maicraft --host 127.0.0.1 --username Bot --events-disabled chat,playerJoined

方式二：配置文件（适合复杂配置）

如果你需要复杂的配置，或者想保存配置以便重复使用，可以使用配置文件：

首先获取配置文件模板：

npx 用户

# 复制配置文件模板到当前目录
npx -y maicraft --init-config

源码安装用户

# 复制配置文件模板
cp config-template.yaml config.yaml

然后编辑 config.yaml 配置你的设置：

minecraft:
  host: 127.0.0.1        # Minecraft 服务器地址
  port: 25565            # 服务器端口
  username: MaiBot       # 机器人用户名
  auth: offline          # 认证方式：offline | microsoft | mojang

# 日志配置
logging:
  level: INFO            # 日志级别：DEBUG | INFO | WARN | ERROR
  enableFileLog: true    # 是否启用文件日志
  useStderr: true        # MCP 模式建议开启

# 可选：禁用特定事件
disabledEvents:
  - chat                 # 聊天事件
  - playerJoined         # 玩家加入
  # - death              # 其他事件...

# 其他高级配置...
# ……

提示： 你也可以混合使用两种方式，先用配置文件设置基础配置，再用命令行参数覆盖特定设置。

启动

现在你可以直接启动 Maicraft：

方式一：npx 用户

# 直接启动（结合上面的命令行参数使用）
npx -y maicraft --host 127.0.0.1 --username MyBot

# 或使用配置文件启动
npx -y maicraft /path/to/config.yaml

方式二：源码安装用户

# 开发模式（热重载，适合开发调试）
pnpm dev

# 生产模式（需要先构建）
pnpm build
pnpm start

启动成功后，你会看到类似以下的输出：

[INFO] Maicraft 客户端已启动，按 Ctrl+C 退出
[INFO] 日志文件位置: /path/to/logs/maicraft-2024-01-15T10-30-00.log
[INFO] WebSocket日志服务器已启动: ws://localhost:20915/ws/mcp-logs

测试

方式一：npx 用户

# 需要先安装mcp-inspector
npm install -g @modelcontextprotocol/inspector

# 列出已注册的工具
mcp-inspector --cli --config mcp-inspector.json --server maicra

... [View full README on GitHub](https://github.com/ChangingSelf/maicraft-mcp-server#readme)