Skip to main content
Glama
Sign In
craftpilot-mcp

craftpilot-mcp

by laur221
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

CraftPilot

License: MIT npm Minecraft Loader

CraftPilot lets AI assistants such as Claude see and control a running Minecraft client. It has two parts:

  • CraftPilot mod (craftpilot-mod): a client-side Fabric mod that runs a local HTTP API inside the game.

  • craftpilot-mcp (this package): an MCP (Model Context Protocol) server that exposes that API as tools over stdio.

Architecture

Claude / MCP client
        |  (MCP over stdio)
        v
  craftpilot-mcp
        |  (HTTP + Bearer token)
        v
  http://127.0.0.1:25599
        |
        v
  CraftPilot mod in Minecraft

Related MCP server: mcdev-mcp

Install

  1. Put the CraftPilot jar and Fabric API into your Minecraft client's mods folder (Fabric 1.21.1).

  2. Install Node.js.

  3. Start the game once. The mod generates a token and writes %USERPROFILE%\.craftpilot\connection.json.

  4. Add the server to your MCP client, e.g. claude_desktop_config.json, and restart it:

{"mcpServers":{"craftpilot":{"command":"npx","args":["-y","github:laur221/craftpilot"]}}}

Local development variant (after npm run build):

{"mcpServers":{"craftpilot":{"command":"node","args":["D:\\mods\\craftpilot-mcp\\dist\\index.js"]}}}

In game, /craftpilot setup or the "Copy AI setup" button copies the config for you.

Configuration

  • %USERPROFILE%\.craftpilot\connection.json holds port, token and gameDir. The MCP server re-reads it on every call, so restarting the game with a new token just works.

  • Environment overrides: CRAFTPILOT_PORT, CRAFTPILOT_TOKEN.

  • Mod settings live in <gameDir>/config/craftpilot.json (port, token, enabled, keepRunningUnfocused, per-command toggles). Edit them in game via the pause-menu icon button, Mod Menu, or /craftpilot config.

  • Other commands: /craftpilot status, /craftpilot token reset.

If the game is not running or the connection file is missing, tools return Minecraft with CraftPilot is not running. Each HTTP call has a 15 s timeout. Responses with ok:false are returned as tool errors.

Tools

Tool

Description

mc_status

Client state: world, screen, player, window, FPS, version

mc_screenshot

Screenshot as an image (maxWidth, default 1280)

mc_screen

List widgets on the current screen with labels and GUI coordinates

mc_click_widget

Click a widget by label or id

mc_click

Click at scaled GUI coordinates

mc_scroll

Scroll the mouse wheel at GUI coordinates

mc_key

Press a key by GLFW name

mc_type

Type text into the focused field

mc_command

Run a slash command and return chat output

mc_chat

Send a chat message

mc_chat_log

Read the last N chat lines

mc_move

Hold movement keys for N ticks

mc_look

Set rotation (absolute or relative)

mc_hotbar

Select hotbar slot 0-8

mc_use

Hold use (right-click) for N ticks

mc_attack

Hold attack (left-click) for N ticks

mc_inventory

List inventory contents

mc_world

List/open/create/leave singleplayer worlds

mc_respawn

Respawn and close the death screen

mc_capabilities

Show which tools are enabled or disabled in settings

Security notes

  • The API binds to 127.0.0.1 only and every request needs Authorization: Bearer <token>.

  • The token is 32 random hex characters; reset it with /craftpilot token reset.

  • Each endpoint can be disabled in the mod settings; a master switch disables the whole API.

  • The mod is client-only and disabled on dedicated servers. It sends nothing to the internet.

  • Intended for singleplayer and testing. Do not use it on public servers or to cheat.

  • Anyone who can read your connection.json can control your client, so keep it private.

Development

Build the mod:

cd craftpilot-mod
gradlew build

Build the MCP server:

cd craftpilot-mcp
npm install
npm run build

The HTTP API is documented in craftpilot-mod/API.md.

License

MIT

Disclaimer

CraftPilot is not affiliated with Mojang, Microsoft or Anthropic.

Available Tools

23 tools
mc_attackB

Press the attack (left-click) key for N ticks.

Inputs: ticks.

mc_capabilitiesA

List which CraftPilot commands are enabled/disabled in the in-game CraftPilot settings. Disabled tools return an error saying so.

Inputs: no named parameters.

mc_chatC

Send a chat message as the player.

Inputs: message (required).

mc_chat_logB

Get the last N chat lines (newest last).

Inputs: limit.

mc_clickB

Click at scaled GUI coordinates on the current screen (see mc_status scaledWidth/Height).

Inputs: x (required), y (required), button.

mc_click_widgetA

Click a widget on the current screen by label (case-insensitive, exact then contains) or by id from mc_screen.

Inputs: id, label, button.

mc_commandA

Run a slash command (without leading slash) and return chat output received in the next ~500ms.

Inputs: command (required).

mc_gotoA

Walk to world coordinates by itself using simple client-side pathfinding (loaded chunks only, max 128 blocks). Returns immediately; poll mc_goto_status. Fails with 'no path' if unreachable.

Inputs: x (required), y (required), z (required), sprint.

mc_goto_statusA

Status of the current mc_goto walk: active, remaining nodes, position, result (running|arrived|failed:|stopped).

Inputs: no named parameters.

mc_goto_stopA

Stop the current mc_goto walk and release the movement keys.

Inputs: no named parameters.

mc_hotbarB

Select a hotbar slot (0-8).

Inputs: slot (required).

mc_inventoryA

List inventory contents (main, armor, offhand): slot, item id, count, name.

Inputs: no named parameters.

mc_keyA

Press a key by GLFW name (escape, enter, tab, backspace, up/down/left/right, f1-f12, space, letters, digits...). Behaves like a real key press in-game and in screens.

Inputs: key (required), mods, action.

mc_lookB

Set player rotation: absolute (yaw/pitch) or relative (dyaw/dpitch), in degrees.

Inputs: yaw, dyaw, pitch, dpitch.

mc_moveB

Hold movement keys for N client ticks (20 ticks = 1 second).

Inputs: back, jump, left, right, +4 more.

mc_respawnA

Respawn the player and close the death screen.

Inputs: no named parameters.

mc_screenA

List widgets on the current Minecraft screen with labels and GUI coordinates; use with mc_click_widget.

Inputs: no named parameters.

mc_screenshotB

Take a screenshot of the Minecraft window (returned as an image). Downscaled to maxWidth.

Inputs: maxWidth.

mc_scrollC

Scroll the mouse wheel at scaled GUI coordinates on the current screen.

Inputs: x (required), y (required), amount (required).

mc_statusA

Get Minecraft client state: in world or not, current screen, player position/health/food, window size, GUI scale, FPS, version.

Inputs: no named parameters.

mc_typeB

Type text into the focused field/screen, character by character.

Inputs: text (required).

mc_useB

Press the use (right-click) key for N ticks.

Inputs: ticks.

mc_worldB

Manage singleplayer worlds from the title screen: list, open, create, or leave the current world.

Inputs: action (required), name, cheats, gameMode.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 23 tools

    Disambiguation4/5

    Tools are grouped into clear functional families (movement, screen interaction, chat, inventory, world, status), and the potentially confusing pairs are explicitly distinguished in their descriptions (mc_click by coordinates vs mc_click_widget by label; mc_chat vs mc_command; mc_move vs mc_goto). Minor residual overlap exists because mc_use/mc_attack are effectively specialized key presses that mc_key can also perform, but the tick-duration semantics make the intent clear.

    Naming Consistency4/5

    Every tool shares a uniform mc_ prefix and snake_case form, with grouped prefixes for related operations (mc_goto/mc_goto_stop/mc_goto_status, mc_chat/mc_chat_log). A few tools are noun-only (mc_status, mc_screenshot, mc_inventory, mc_world, mc_hotbar) rather than verb_noun, so the pattern is predictable but not strictly uniform.

    Tool Count4/5

    23 tools is on the heavy side of the rubric, but the domain is a full Minecraft client control surface, and each tool covers a distinct capability (look, move, use, attack, screen widgets, inventory, chat, world management, pathfinding). Only marginal candidates for merging exist (mc_use/mc_attack into mc_key, mc_goto_stop into mc_goto), so the set is slightly over-scoped but reasonable.

    Completeness4/5

    The surface covers the core agent lifecycle: observe state (status, screenshot, screen, inventory, chat log), act (move, look, key, click, type, use, attack), navigate (goto + status/stop), and manage worlds and respawn. Gaps are minor and mostly workaroundable — inventory is read-only (no direct slot-to-slot item moves or drops), and there is no explicit block-break/place or container-transfer operation beyond raw attack/use/click.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers