Skip to main content
Glama

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.

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

  1. Download the mod JAR for your Minecraft version from GitHub Releases (not the -sources.jar).

  2. Put it in your game's mods/ folder together with JsMacros and, preferably, Baritone.

  3. Launch the game and press F8 to open the settings screen.

  4. 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

mods/ inside the installation's Game Directory. By default .minecraft/mods/ on Windows/Linux, ~/Library/Application Support/minecraft/mods/ on macOS

Prism Launcher, MultiMC

Open the instance's Minecraft folder; usually .minecraft/mods/ inside the instance folder

Other launchers

Open the instance's game folder and use its mods/

2. Install the Skill

npx skills add MakkCH/minecraft_mcp --skill minecraft-mcp -g

Pick 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/"

(MCP documentation)

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@latest

For 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

minecraft_mcp

Transport

stdio

Command

npx

Arguments

-y and @makkch/minecraft-mcp@latest (two separate arguments)

Environment

MINECRAFT_MCP_TOKEN, MINECRAFT_MCP_URL

Good to know:

  • npx -y @makkch/minecraft-mcp@latest is meant to be run by your MCP client. Run it yourself in a terminal and you only get a process waiting for input.

  • @latest selects the version tagged latest on 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

/mcp stop

Disables the agent, stops MCP tasks, runs their registered cleanup, and releases pressed keys

/mcp start

Allows the agent to act again

/mcp status

Shows whether control is enabled and how many tasks are running

/mcp config or F8

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.

  1. Enable Allow remote in the game's F8 settings and press Apply. Allow the game port through its firewall.

  2. In your agent's MCP configuration, set MINECRAFT_MCP_URL to the game's address, such as http://192.168.1.20:28473/.

  3. 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-host

Set 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 /mcp start in the game

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 mods/

MCP server (npm)

With @latest, restart the MCP connection. If pinned, change the version number in your configuration first

Skill

npx skills update minecraft-mcp -g (use -p for a project-level install)

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 configuration

Build 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   # default

Use 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/distributions

The package contains the MCP server, its dependencies, the Skill, plugin metadata, README, and icons. Gallery project files are left out.

Tests

Command

Checks

Needs

npm test

MCP negotiation, tool list, argument validation

Nothing

npm run test:execute

Arguments, local files, diagnostics, 30-second waits

A local running game

npm run test:runtime

Script execution, game-thread callbacks, mod discovery, screenshots

A running game

npm run test:mod

Settings screen, token change and authentication, Mod Menu entry (if installed)

A running game

npm run test:live

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-instance

Without -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 tools
chatA

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

    A3.9/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers