Minecraft MCP
Controls a Minecraft client through MCP by running JsMacros scripts, reading output, taking screenshots, and sending local chat updates.
Execute JavaScript code or a .js file in a fresh JsMacros context with native/mod APIs, args, configurable wait time, and optional keep_alive; returns a task ID and buffered output.
Read newly buffered output and native execution state for a running task, including errors and stack traces.
Stop a specific MCP-owned task or all tasks, running registered cleanup and releasing held keys when stopping all.
Capture the actual Minecraft framebuffer, including HUD, menus, and overlays, as an image.
Display progress or status messages in the local player's Minecraft chat with the configured tag, name, and colors.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Minecraft MCP Explore the nearby forest and mark any villages you find"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The agent controls your character with JsMacros scripts: it writes one, runs it, reads the output, takes a screenshot, and reports in chat. You watch from your own point of view and type /mcp stop whenever you want the controls back.
Gallery
Everything here was done by an agent through Minecraft MCP. Browse all projects.
The banner scene was built and captured in Minecraft by GPT-6 Astra using Minecraft MCP.
Related MCP server: Minecraft MCP Server Pro
Requirements
Requires Fabric and one of the Minecraft versions listed below.
Minecraft Java Edition | Download this JAR group | Baritone API Fabric (optional) |
26.1, 26.1.1, 26.1.2 | 26.1 | 1.18.0 |
26.2 | 26.2 | 1.19.0 |
26.3 | 26.3 | 1.20.0 |
Component | Requirement |
Fabric Loader | 0.19.5 or later |
Java | 25 or later |
JsMacros Reloaded | 2.2.1, same JAR group as above (bundles the Fabric API modules this mod needs) |
Node.js | 22+ for the MCP server; 22.20+ for Skills CLI |
Agent | Codex, Claude Code, Claude Desktop, Cursor, or any client with stdio MCP support |
Baritone | Optional, strongly recommended |
Scripts, screenshots, and direct player control work without Baritone. In that case, the agent has to script its own pathfinding and resource gathering.
Installation
There are three things to install:
Component | Where | What it does |
Mod | Minecraft | Receives commands and runs them in the game |
Skill | Agent | Teaches the agent how to write scripts and which APIs exist |
MCP server | Agent | Exposes the game as tools the agent can call |
We recommend running the agent, MCP server, and Minecraft on the same computer.
1. Install the mod
Download the mod JAR for your Minecraft version from GitHub Releases (not the
-sources.jar).Put it in your game's
mods/folder together with JsMacros and, preferably, Baritone.Launch the game and press F8 to open the settings screen.
Copy the token and note the port (normally
28473). You need both in step 3.
/mcp config opens the same screen. So does Mods → Minecraft MCP → Configure if you have Mod Menu. F8 can be rebound in Minecraft's Controls settings.
The screen also lets you enable Allow remote (off by default), configure automatic startup, and customize the [AGENT] chat tag, name, and colors.
Launcher | Location |
Official Minecraft Launcher |
|
Prism Launcher, MultiMC | Open the instance's Minecraft folder; usually |
Other launchers | Open the instance's game folder and use its |
2. Install the Skill
npx skills add MakkCH/minecraft_mcp --skill minecraft-mcp -gPick your agent when prompted, or name it directly with -a codex, -a claude-code, or -a cursor. The -g flag installs the Skill for all your projects. Leave it out to install for the current project only.
If your client has no Skill support, give the agent SKILL.md as instructions and make sure it can read the files that document refers to.
3. Add the MCP server
Add a stdio MCP server in your agent client, using the token from step 1 and the game's URL. The URL defaults to http://127.0.0.1:28473/; if F8 shows a different port, change the port in the URL.
Add this to ~/.codex/config.toml. If a minecraft_mcp entry already exists, edit it instead of adding a second one. (Codex MCP documentation)
[mcp_servers.minecraft_mcp]
command = "npx"
args = ["-y", "@makkch/minecraft-mcp@latest"]
[mcp_servers.minecraft_mcp.env]
MINECRAFT_MCP_TOKEN = "YOUR_TOKEN"
MINECRAFT_MCP_URL = "http://127.0.0.1:28473/"claude mcp add --env MINECRAFT_MCP_TOKEN=YOUR_TOKEN \
--env MINECRAFT_MCP_URL=http://127.0.0.1:28473/ --transport stdio --scope user minecraft_mcp \
-- npx -y @makkch/minecraft-mcp@latestFor Cursor, add this to ~/.cursor/mcp.json or your project's .cursor/mcp.json. For Claude Desktop, add it to claude_desktop_config.json. (Cursor documentation · Claude Desktop guide)
{
"mcpServers": {
"minecraft_mcp": {
"command": "npx",
"args": ["-y", "@makkch/minecraft-mcp@latest"],
"env": {
"MINECRAFT_MCP_TOKEN": "YOUR_TOKEN",
"MINECRAFT_MCP_URL": "http://127.0.0.1:28473/"
}
}
}
}Field | Value |
Name |
|
Transport |
|
Command |
|
Arguments |
|
Environment |
|
Good to know:
npx -y @makkch/minecraft-mcp@latestis meant to be run by your MCP client. Run it yourself in a terminal and you only get a process waiting for input.@latestselects the version taggedlateston npm. To pin a version, replace it with a version number that is compatible with your mod.The token gives control of your game. Keep it out of shared repositories.
4. Try it
Restart your client's MCP connection, start a new chat, and say:
Inspect my Minecraft client and tell me what you can see.
Gather some wood nearby and keep me updated in chat.
If nothing happens, see Connection help.
Archive (.tgz): download it from the release and extract it. In your MCP configuration, set the command to node and the argument to the absolute path of src/server.mjs; the environment variables stay the same. Install the Skill as in step 2.
Codex plugin: still available and includes the Skill, but not recommended for new installations. Use the standalone setup above to configure the token and URL for each game instance (Codex MCP settings). See Codex plugin installation.
If you already use the plugin and want to switch to the standalone setup above, disable the plugin before enabling the standalone MCP server and Skill.
Staying in control
In Minecraft | Effect |
| Disables the agent, stops MCP tasks, runs their registered cleanup, and releases pressed keys |
| Allows the agent to act again |
| Shows whether control is enabled and how many tasks are running |
| Opens the settings screen |
While disabled, the agent can still take screenshots. If another mod continues an action, use that mod's stop control.
Disconnecting from a server or leaving a singleplayer world cancels running tasks. Changing dimensions does not.
[AGENT]messages appear only in your own chat. They are not sent to multiplayer servers.The mod interface is in English.
The mod adds no blocks, items, or entities, so removing it needs no changes to your save. What the agent does is as real as what you do: it changes your world and inventory.
Remote connection
Script contents can be sent to another computer, but require() and other file access use the game computer's filesystem. Use self-contained scripts or prepare dependencies on the game computer yourself.
Enable Allow remote in the game's F8 settings and press Apply. Allow the game port through its firewall.
In your agent's MCP configuration, set
MINECRAFT_MCP_URLto the game's address, such ashttp://192.168.1.20:28473/.Use the token from the game's F8 screen, then restart the MCP connection.
Alternatively, leave Allow remote off and use an SSH tunnel:
ssh -N -L 38473:127.0.0.1:28473 user@game-hostSet the URL to http://127.0.0.1:38473/. MINECRAFT_MCP_URL also accepts HTTPS, IPv6, custom ports, and proxy path prefixes.
Scripts run with the full permissions of the Minecraft process. Connect only trusted agents; use SSH or HTTPS across untrusted networks to protect the token and script contents. Custom addresses and Allow remote require 0.4.0 or later.
Connection help
Symptom | What to do |
Connection refused | Check that you launched the instance with the mod, and compare the port with F8 |
Authentication failed / HTTP 401 | The token does not match F8. Fix it and restart the MCP connection |
Agent control disabled | Type |
Agent cannot find the tools | Check that the MCP server is enabled and Node.js is installed, then start a new chat |
Port already in use | When running several game instances, give each a different port in F8 |
Incompatible Minecraft MCP versions | Update the mod and MCP server to compatible versions |
Remote connection refused / 404 | Check in order: Allow remote, IP and port, firewall, tunnel or proxy, URL prefix |
Updating
Component | How |
Mod | Download the new JAR from Releases, close the game, replace the old file in |
MCP server (npm) | With |
Skill |
|
Archive | Replace the extracted folder and restart the MCP connection |
Codex plugin | Update from the source you installed it from, then start a new chat |
Updating does not touch your settings in the game or in the agent client. Update the MCP server and installed Skill together. Check that the MCP server is compatible with your mod.
Versions and compatibility
The mod and the agent package (MCP server, Skill, Codex plugin) share the first two parts of the version number. The third part moves independently.
Same first two parts means compatible. Mod 0.4.2 works with MCP server 0.4.0.
When the interface between the two changes, both move to the next minor version together.
The MCP server checks the mod version when connecting. Different major or minor versions are rejected before game actions run.
Development
src/ MCP server (Node.js, stdio)
skills/minecraft-mcp/ Skill: instructions, API index, script utilities, examples
mod/ Fabric client mod
tests/ Protocol tests and real-client integration tests
scripts/ Developer utilities
assets/ Icons, README media, gallery projects
.codex-plugin/ Codex plugin metadata
.mcp.json MCP server launch configurationBuild the mod
Requires JDK 25. Each Minecraft version group builds its own JAR into build/<profile>/libs/:
./gradlew build -PmcProfile=26.1
./gradlew build -PmcProfile=26.2
./gradlew build -PmcProfile=26.3 # defaultUse gradlew.bat on Windows. The 26.1 group builds against 26.1.2; pass -PmcVersion=26.1 or -PmcVersion=26.1.1 to build against another version in that group.
Package the agent bundle
Requires Node.js 22 or later:
npm ci
mkdir -p build/distributions
npm pack --pack-destination build/distributionsThe package contains the MCP server, its dependencies, the Skill, plugin metadata, README, and icons. Gallery project files are left out.
Tests
Command | Checks | Needs |
MCP negotiation, tool list, argument validation | Nothing | |
Arguments, local files, diagnostics, 30-second waits | A local running game | |
Script execution, game-thread callbacks, mod discovery, screenshots | A running game | |
Settings screen, token change and authentication, Mod Menu entry (if installed) | A running game | |
Movement, Baritone navigation, output, cancellation, markers, scoped stop, and stop-all | A loaded test world; Baritone for navigation |
The game tests connect to a Minecraft client set aside for testing and take its port and token from environment variables. To start one:
./gradlew runClient -PmcProfile=26.1 -PmcpRunDir=/absolute/test-instanceWithout -PmcpRunDir, the run directory is created in the system temporary folder, one per version. When running several test clients, give each its own port and token.
Skill · API index · Mod discovery · Script utilities · Examples
License
MIT © 2026 Mak. Bundled third-party dependencies retain their own licenses.
Available Tools
5 toolschatA
Display a progress message in the player’s local Minecraft chat. The configured tag, name and colors are added automatically. Only the local player sees it.
Inputs: message (required).
executeA
Run JS code OR a .js file in a fresh JsMacros context. Relative file paths resolve from the MCP working directory. Native JsMacros and installed mod Java APIs are available. console.log/print are captured. Waits up to wait_ms for the script body to finish, then returns a task ID and buffered output; retain the ID for read_output or stop when running or active. args is available as mcp.args. keep_alive retains the context after the script body returns; defaults to false. Reaching the wait deadline leaves the script running.
Inputs: args, code, file, wait_ms, +1 more.
read_outputA
Read and consume newly buffered output for a task, plus its native execution state. Use one reader per task. Overflow is marked inline as [ …N bytes truncated… ]. Errors include script stack traces and precede output. Waits until output arrives, the task ends or wait_ms elapses.
Inputs: task (required), wait_ms.
screenshotA
Capture the actual Minecraft framebuffer including HUD, menus and overlays. Returns the image directly.
Inputs: no named parameters.
stopA
Stop one MCP-owned JsMacros task, or all MCP tasks when task is omitted. Runs cleanup registered with mcp.track for the stopped tasks. Stopping all tasks also releases keys held in JsMacros.
Inputs: task.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a largely distinct purpose: execute runs code, stop halts tasks, read_output retrieves buffered output, chat posts a local message, and screenshot captures the framebuffer. The only mild overlap is that chat could be achieved through execute, but the dedicated tool is clearly scoped to player-visible notifications.
All names are lowercase and snake_case where needed, but the verb convention is mixed: execute and stop are bare verbs, read_output follows verb_noun, while chat and screenshot are noun-like labels. Readable, but not a predictable pattern.
Five tools is well-scoped for a JS execution/control server. Each tool covers a distinct part of the execution lifecycle or a useful side operation, and none feels redundant.
The core lifecycle is covered: execute with wait/keep_alive, read_output for output and state, stop for cleanup. Minor gaps include no explicit task listing or status-enumeration tool, but read_output and stop mitigate this enough for agent use.
Maintenance
Related MCP Connectors
Hosted Screenshots MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Generate AI video, images and audio, and browse your history, from any MCP client.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Generate AI images and videos from any compatible MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to remotely control a Minecraft player, including navigation, mining, building, and interaction with the world and other players.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control Minecraft via MCP with configurable versions, creative building commands, survival helpers, and an autonomous agent loop.Apache 2.0
- AlicenseBqualityCmaintenanceEnables AI agents to operate a Minecraft Java Edition player through MCP, supporting movement, mining, crafting, combat, inventory, and chat with structured observations and action results.18MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to control and observe a Minecraft client through tools for state, entities, commands, chat, recording, waiting, and event replay, bridging any agent runtime to the game.MIT