skript-mcp

Skript MCP

This project exposes a small MCP server backed by a permanently running Paper server. Paper, Skript, and the installed addons are the parser: the Python code does not attempt to understand Skript syntax itself.

The default image contains this compatibility profile:

Every downloaded jar is checked during the image build. Override all related URLs and checksums together in .env to use another authoritative profile. Never update only one addon without verifying the complete set.

Skript 2.14.3 is intentional for the 1.21.4 profile. SkBee 3.16.1 is the last SkBee release for Minecraft 1.21.4, and newer Skript 2.15/2.16 releases collide with its Adventure audience type registration. Newer Skript requires moving the whole profile to a newer Minecraft and SkBee release.

Start Paper

Run the setup script. It checks Docker and uv, creates .env with a random RCON password, installs dependencies, builds Paper, and verifies RCON:

./setup.sh

For manual setup, create a local environment file and replace the password with a long random value containing only letters, numbers, dots, underscores, or hyphens:

cp .env.example .env
docker compose build
docker compose up -d --wait

Set PUID and PGID in .env to the output of id -u and id -g. They default to 1000 and let Paper read the host-created mode-0600 temporary files.

Paper logs are mounted at runtime/logs. Host scripts are mounted directly at /server/plugins/Skript/scripts from scripts. World and plugin-generated data remain disposable container state. Only RCON is published, and it is bound to 127.0.0.1:25575; the gameplay port is not published.

Check startup and plugin versions with:

docker compose logs paper
docker compose exec paper sh -c 'nc -z 127.0.0.1 25575'

Run the MCP server

Install and run it with uv:

uv sync
uv run --env-file .env skript-mcp

The MCP process reads these environment variables:

For OpenCode, add a local MCP entry and pass the same RCON password through the environment:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "skript": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/absolute/path/to/skript-mcp", "--env-file", "/absolute/path/to/skript-mcp/.env", "skript-mcp"],
      "enabled": true,
      "environment": {}
    }
  }
}

Restart OpenCode after changing its configuration.

Tools

• skript_check_file(path) validates an existing .sk file by path. Relative paths are resolved under SKRIPT_SCRIPTS_DIR; absolute paths are accepted when they point inside that directory. It reloads the complete script set so functions and other shared definitions from sibling scripts are available.

• skript_reload_file(path) reloads one existing path inside SKRIPT_SCRIPTS_DIR without reloading its siblings.

• minecraft_command(command) runs a privileged command over local RCON.

• minecraft_logs(lines=200) returns a bounded tail of latest.log.

• skript_reset() removes only stale __mcp_check_<uuid>.sk files.

Reload operations are serialized. Diagnostics are parsed primarily from the RCON response because Skript deliberately redirects command diagnostics away from normal server logging; bytes appended to latest.log after the operation offset are captured and merged as a secondary source.

Safety

skript_check_file performs a real reload of every enabled script, not a sandboxed parse. Source containing on load handlers or addon behavior can modify the world, files, or external systems. Only check trusted scripts, and treat minecraft_command and the RCON password as full administrator access.

Run unit tests with:

uv run pytest