minecraft-mcp — Minecraft MCP server: what it does, how to install
This MCP server enables AI agents to control a player character in Minecraft. It runs via JsMacros to execute JavaScript scripts, capture screenshots, and report status in-game.
MIT ★ 26 updated 2026-11-13
claude mcp add --env MINECRAFT_MCP_TOKEN=<MINECRAFT_MCP_TOKEN> --env MINECRAFT_MCP_PORT=<MINECRAFT_MCP_PORT> --env MINECRAFT_MCP_URL=<MINECRAFT_MCP_URL> --transport stdio minecraft-mcp -- npx -y @makkch/minecraft-mcpWhat minecraft-mcp does
The server exposes game functions as tools for an AI agent to interact with Minecraft. To get started, install the Fabric mod in your mods/ folder alongside JsMacros and Baritone, then retrieve your token and port from the in-game settings screen opened by pressing F8.
The agent controls the character by writing and running JavaScript code, receiving outputs and visual feedback. You retain manual control at any time by typing /mcp stop in the game chat. Requirements include Fabric Loader 0.19.5 or later and Java 25 or higher.
What it helps with
- automate resource gathering in Minecraft
- build structures using AI-generated instructions
- navigate and explore game worlds autonomously
Example prompts for the agent
- Build a stone workshop by the riverside
- Locate the nearest village and harvest resources
- Collect iron to craft tools
How to install minecraft-mcp
Platform CLI
claude mcp add --env MINECRAFT_MCP_TOKEN=<MINECRAFT_MCP_TOKEN> --env MINECRAFT_MCP_PORT=<MINECRAFT_MCP_PORT> --env MINECRAFT_MCP_URL=<MINECRAFT_MCP_URL> --transport stdio minecraft-mcp -- npx -y @makkch/minecraft-mcpReplace <…> with your own values
Platform CLI
codex mcp add minecraft-mcp --env MINECRAFT_MCP_TOKEN=<MINECRAFT_MCP_TOKEN> --env MINECRAFT_MCP_PORT=<MINECRAFT_MCP_PORT> --env MINECRAFT_MCP_URL=<MINECRAFT_MCP_URL> -- npx -y @makkch/minecraft-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"minecraft-mcp": {
"command": "npx",
"args": [
"-y",
"@makkch/minecraft-mcp"
],
"env": {
"MINECRAFT_MCP_TOKEN": "<MINECRAFT_MCP_TOKEN>",
"MINECRAFT_MCP_PORT": "<MINECRAFT_MCP_PORT>",
"MINECRAFT_MCP_URL": "<MINECRAFT_MCP_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"minecraft-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@makkch/minecraft-mcp"
],
"env": {
"MINECRAFT_MCP_TOKEN": "<MINECRAFT_MCP_TOKEN>",
"MINECRAFT_MCP_PORT": "<MINECRAFT_MCP_PORT>",
"MINECRAFT_MCP_URL": "<MINECRAFT_MCP_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e MINECRAFT_MCP_TOKEN=<MINECRAFT_MCP_TOKEN> -e MINECRAFT_MCP_PORT=<MINECRAFT_MCP_PORT> -e MINECRAFT_MCP_URL=<MINECRAFT_MCP_URL> minecraft-mcp npx -y @makkch/minecraft-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about minecraft-mcp
How to install minecraft-mcp?
Download the JAR from GitHub, place it in your mods/ folder, and press F8 in-game to copy your token and port. Configure your agent client to use the stdio MCP server with these credentials.
What does minecraft-mcp do?
It bridges your Minecraft client and an AI agent, allowing the agent to perform in-game actions by executing custom JavaScript scripts.
What is required to use minecraft-mcp?
You need Minecraft Java Edition with Fabric, JsMacros Reloaded, Java 25 or later, and Node.js version 22+ to run the MCP server.