Sculkwire

MCP Tools

See the tool reference for what each tool does and its inputs.

Related MCP server: Minecraft RCON MCP Server

Features

• Versioned knowledge. Docs, Script API, components, commands, Molang, vanilla examples and changelogs, for both stable and preview. Every answer states the game version it describes.

• Validation. Every problem is reported with a file, line, column and rule code. Regolith projects are built with rgl first.

• Bedrock Dedicated Server. Load checks, headless GameTest runs and script profiling. Regolith projects are built with rgl first.

• Live game bridge. Launch the real client in a private test world with your packs, reload after edits, read the content log, query the world, take screenshots and send keyboard and mouse input, on Windows and Linux. On Linux the input stays inside gamescope, so your own mouse and keyboard stay yours, and the game can also run off-screen. On Windows the agent uses the system keyboard and mouse while the game window is in the foreground, and stops when you switch away. A sign-in error at launch is recovered without restarting the game.

• Player control. The agent plays like a person through player_act, on Linux and Windows. That covers smooth camera movement, pathfinding over blocks, ladders, water and gaps, and combat against zombies, skeletons, spiders and creepers. play runs a goal in the background, with an optional decision model as an advisor. On Windows a running action stops and a play job pauses while the game window is not in the foreground.

• Game files. Reads your installed PC copy of the game: its version, and the per-version vanilla_1.x packs a world's base_game_version pins, unpacked from .brarchive into plain folders you can grep or diff against.

• Extensions. Packages in your sculkwire config folder can add MCP tools, CLI commands and an in-process input route. See Extensions.

• Benchmarks. sculk bench builds arenas in a test world and measures combat and movement skills.

Quick Start

sculkwire needs Node.js 22.18 or newer and git. Both install paths below put a sculk command on your PATH and register a stable launcher with your MCP client, so later updates never change the client configuration. Install and Update has the details.

Install With Your Agent

Paste this into your AI agent harness:

Install the sculkwire MCP server: clone https://github.com/ve3dy/sculkwire.git and follow the "Agent Install" steps in its docs/install.md.

The agent checks Node.js and git, runs the installer, registers sculkwire with itself and runs sculk doctor. It asks one optional question about a decision model (default None) and never asks for an API key.

Install With a Script

Linux and macOS:

git clone https://github.com/ve3dy/sculkwire.git
cd sculkwire
./install.sh

Windows (Windows PowerShell 5.1 or PowerShell 7):

git clone https://github.com/ve3dy/sculkwire.git
cd sculkwire
.\install.ps1

The installer checks Node.js and git, installs the newest release into your data folder, puts sculk on your PATH (it says what it changes first; --no-path / -NoPath skips it) and runs sculk setup. It asks two questions. The first is the optional decision model, where pressing Enter keeps None (the default). The second is which MCP clients to register with. --yes skips both questions, and --decision none|openrouter|zenmux|local and --register <clients> answer them from the command line (-Yes, -Decision and -Register in PowerShell). API keys are never passed as flags. Set OPENROUTER_API_KEY or ZENMUX_API_KEY in your environment, or run sculk setup in a terminal to save one.

Or install in one line. Piped, the installers read their options from SCULKWIRE_* environment variables, see Installers.

curl -fsSL https://raw.githubusercontent.com/ve3dy/sculkwire/main/install.sh | sh

irm https://raw.githubusercontent.com/ve3dy/sculkwire/main/install.ps1 | iex

sculk doctor checks the game install, BDS, rgl, uv, the decision model and the installed version, one line per problem with a fix for your OS.

Manual Setup

To run from a git checkout instead (development checkouts never update themselves), run npm install in the clone and add sculkwire to your MCP client configuration by hand:

{
  "mcpServers": {
    "sculkwire": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sculkwire/src/cli.ts", "mcp"]
    }
  }
}

The first knowledge request downloads docs, typings and vanilla samples, which takes about a minute. Run sculk knowledge update (node src/cli.ts knowledge update in a checkout) to do this ahead of time.

Updating

An installed sculkwire updates itself. When the MCP server starts, it checks for a new release at most once a day in the background. A new release is downloaded, installed and tested, then used by the next session. The running session keeps its version and sends a notice that a restart picks up the update. A failed check (offline, no access to the repository) changes nothing.

sculk update --check            # Show whether a newer release exists
sculk update                    # Install the newest release now
sculk update --rollback         # Switch back to the version before the last update
sculk update --channel off      # No automatic updates (release and main are the other channels)

The sculkwire_version tool and sculk doctor report the running version and any update waiting for the next session. In a development checkout, sculk update prints the git pull command instead.

Data sources update on their own as well. Vanilla samples, Script API typings, docs, changelogs, Bedrock Dedicated Server and rockide/schemas are each checked at most once a day, and a new upstream release is used without a sculkwire release or sculk knowledge update. The MCP server downloads new builds in the background; a CLI command only refreshes the version pins and leaves the downloads to the next MCP session or sculk knowledge update. Offline, the last copy keeps working. sculk knowledge status shows per source the version in use, the newest upstream and the last check.

Optional Decision Model

The play action of player_act picks its tactics with built-in scores and works without a decision model. When one is configured (Jev through OpenRouter or ZenMux, or Kev on your own GPU), play asks it as an advisor at game speed, and game_launch can ask it to find a button when its sign-in recovery is stuck. Nothing else uses one, and the default is none. See Decision Model for setup, Kev and the config file.

Requirements

CLI

All features are also available from the command line.

node src/cli.ts validate path/to/addon            # Exit code 1 when errors are found
node src/cli.ts bds gametest path/to/addon        # Run GameTests
node src/cli.ts game check path/to/addon --screenshot shot.png
node src/cli.ts api Entity.applyDamage
node src/cli.ts bench combat --runs 3             # Measure the player skills
node src/cli.ts doctor                            # Check the machine
node src/cli.ts --help                            # List all commands

Data Sources

• Vanilla samples, @minecraft/* typings, Microsoft Learn docs, changelogs and Bedrock Dedicated Server are downloaded into your local cache and update on their own.

• rockide/schemas by the Rockide project provides the JSON schemas used first by the validator and by component_lookup.

• Packs unpacked from your installed copy of the game stay in your local cache.

• The icon is a pixel-art sculk block with a glowing pixel Model Context Protocol mark above it.

License

MIT, see LICENSE.

NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.