maicraft

Maicraft is a Minecraft MCP server built on top of mineflayer that enables a bot to join and interact with a Minecraft server. It is designed to work with the Amaidesu project and can also function as a standalone MCP server. The repository provides tooling to run Maicraft via npx, as well as options for local builds or global installation. You can test and inspect its capabilities using the MCP Inspector tooling to list and call available tools, and you can observe actions like pathfinding, mining, and bot interactions through the action/tool framework described in the documentation. The server exposes a structured set of actions (MCP Tools) that scripts can invoke, and it supports debugging views and WebSocket-based log streams for real-time observation.

Prerequisites:

• Node.js and npm or pnpm installed on your system
• A configured Minecraft server (any version, with automatic detection, recommended 1.20.4)

Option A: Run via npx (quick start)

1. Ensure you have Node.js/npm installed.
2. Run a configuration snippet via npx (as shown in the README):

# Start Maicraft using npx (example)
npx -y maicraft --host 127.0.0.1 --port 25565 --username MaiBot --auth offline

Option B: Global installation (faster startup after initial install)

1. Install globally:

npm install maicraft -g

2. Then configure with a local mcp config that points to the global package:

{
  "mcpServers": {
    "maicraft": {
      "command": "maicraft",
      "args": ["--host","127.0.0.1","--port","25565","--username","MaiBot","--auth","offline"]
    }
  }
}

Option C: Local build from source (requires Git and pnpm)

1. Clone the repository and install dependencies:

git clone https://github.com/ChangingSelf/maicraft-mcp-server.git
cd maicraft-mcp-server
pnpm install

2. Build the project (if you want a dist/main.js):

pnpm run build

3. Run with a local node command or configured mcp config pointing to the built file.

Option D: Using TypeScript source directly (tsx) for quick runs

1. Install tsx if needed and run via npx (examples shown in the README):

npx -y maicraft --host 127.0.0.1 --username MyBot

Prerequisites for all methods: a running Minecraft server reachable by the Maicraft bot, appropriate network access, and a compatible Node.js environment.

Tips and common considerations:

• You can choose between command-line options or a config file (config.yaml) for Maicraft settings. The config supports host, port, username, auth method, and logging options.
• For testing tools, install the MCP Inspector tool to list and invoke Maicraft actions (e.g., query_state) and to perform state checks or other tests. You can use either the CLI or the pnpm scripts depending on your installation method.
• WebSocket logs are available at ws://localhost:20915/ws/mcp-logs by default; you can enable/modify this in the config if needed.
• If you experience slow startup with npx, consider installing Maicraft globally or using a local build to reduce download time.
• The system supports both runtime command-line overrides and configuration files, allowing flexibility for development and production deployments.