Minecraft MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MINECRAFT_MCP_PORT | No | Explicit port value that overrides the value in the connection file. | |
| MINECRAFT_MCP_TOKEN | No | Explicit token value that overrides the value in the connection file. | |
| MINECRAFT_MCP_CONNECTION | No | Path to a connection file to use instead of the default ~/.config/minecraft-mcp/connection.json. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Controls the player's real Minecraft client. Player /mcp stop takes priority.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| 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. |
| 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. |
| 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. |
| screenshotA | Capture the actual Minecraft framebuffer including HUD, menus and overlays. Returns the image directly. |
| 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.