McClaude

Let Claude Code or Codex develop on a live Minecraft server.

McClaude bridges Claude Code or Codex and a running Minecraft server so your agent can read the console, run commands, and edit plugin files like Skript scripts in real time, without ever leaving the IDE. Install the integration in either agent or both, then use whichever you prefer.

What your agent can do

Tool	Purpose
list_servers	Get all servers reachable with the current token
read_console	Read recent console output (50 lines by default)
send_command	Execute a server command as console (no leading slash)
send_command_as	Execute a command as a specific online player (proper sender, captures console output — chat-only output is not captured)
get_server_info	Live TPS, MOTD, player count, version
list_plugins	Installed plugins with versions
get_player_info	Player details: health, location, gamemode, armor, effects (optional full inventory; optional styled for &-coded names/lore)
get_open_inventory	Read the GUI/inventory a player currently has open (slots, items, title) — useful for verifying custom GUIs without screenshots
gui_open	Open a collaborative GUI design canvas for a player (free item movement). Supports all inventory types: chest, hopper, anvil, furnace, workbench, etc. Session persists when closed — reopen with /mcclaude gui
gui_read	Read current design GUI state. Records a snapshot for conflict detection
gui_set	Set specific slots (incremental). Detects if player modified since last read — forces re-read before overwriting
gui_close	End design session, return final layout for conversion to code
skript_eval	Run Skript effect(s) — single (code) or batch (codes array, local variables persist across the batch). Validates no unquoted newlines before sending. Captures send/broadcast output directly (Skript only)
search_skript_syntax	Query SkriptHub for Skript syntax (no server needed)

In addition to these tools, the user client mounts the server's filesystem as a Windows drive, so your agent reads and edits plugin files (.sk, .yml, etc.) using local file or shell tools. The drive root and each server's mounted root expose virtual, read-only CLAUDE.md and AGENTS.md files with equivalent guidance. Server instructions describe installed plugins (Skript, skript-reflect, skript-gui, Citizens, PlaceholderAPI, TAB, FancyHolograms, LuckPerms, Vault, etc.) and how to work with them. These generated files take precedence over same-named remote files at those roots; the remote files are not modified.

Prerequisites

• Windows for the user client. The drive-mount layer uses Windows-only APIs (WNetAddConnection2W). The MCP server, intermediate server, and Minecraft plugin all run anywhere; only the local mount on the developer's machine is Windows-restricted.
• Java 21+ to build and run the Minecraft plugin.
• Paper 1.21+ as the server platform.
• Node.js 20+ to build and run the intermediate server and MCP server.
• Python 3.10+ to run the user client (or rebuild the bundle).

Setup

1. Build and host the intermediate server

cd intermediate-server
npm install
npm run build
npm start          # listens on :3000 by default

Or deploy to a Node.js host (Pterodactyl, Render, Heroku, etc.). The repo root has a thin package.json whose postinstall builds intermediate-server/ and whose start runs it. So git clone + npm install + npm start is enough. On Pterodactyl with a generic Node.js egg, enable auto-update on the egg and it'll re-pull + rebuild on every restart.

2. Build and install the Minecraft plugin

cd minecraft-plugin
./gradlew shadowJar

Drop build/libs/McClaude.jar into your server's plugins/ folder. On first start it generates plugins/McClaude/config.yml. Set the server-url, server-name, and a fresh server-token (any UUID).

3. Run the user client

End users only need dist/mcclaude.py and dist/requirements.txt:

pip install -r requirements.txt
python mcclaude.py

The TUI walks through setup (server URL + token) and lets you select Claude Code, Codex, or both. It installs one shared MCP bundle and registers it with each selected agent:

• Claude Code: user-level mcpServers.mcclaude in ~/.claude.json.
• Codex: user-level mcp_servers.mcclaude in $CODEX_HOME/config.toml, defaulting to ~/.codex/config.toml. This supports the native CLI and IDE extension using that Codex home; the Codex CLI does not have to be installed to write the configuration.

Other agents' registrations and unrelated settings are preserved. Both registrations contain the server token, so treat those configuration files as private. Installation results are shown separately; if one fails, correct its configuration/dependencies and retry with Repair MCP.

Settings remembers your selection. Press Save & Install to apply it; checking a box alone does not install anything. Saving settings, repairing, and accepting MCP updates applies to the selected agents. The Codex configuration folder defaults to the inherited CODEX_HOME or ~/.codex, and can be changed to match the Codex client you use. IDEs such as Air may set their own private CODEX_HOME; choose your normal ~/.codex for a standalone Codex client. The chosen folder is remembered, and installation confirms the configuration file written. Older McClaude configurations default to Claude Code. Unchecking an agent does not uninstall its existing registration; it stops updating that agent's configuration. Remove the mcclaude entry in that agent if you want to uninstall it. Reset resets McClaude's local settings, not agent registrations.

Restart the selected agents after installation or updates. Use Mount to map the live server filesystem to M:\, then open M:\<server-name> as your agent's working folder so its server instructions are discovered. Keep McClaude running while editing. If you start from the drive root, read the target server's instruction file before working there.

For Codex, use native Windows execution and allow the mounted server folder under your chosen permissions. If tools connect but files are inaccessible, check whether the Codex execution environment can see the mounted drive; registering MCP does not grant filesystem access. WSL/remote hosts require their own mount and configuration and are not covered by this Windows client. For scripted codex exec runs on the non-Git mounted folder, use --skip-git-repo-check.

To rebuild the bundle yourself: python build.py from the repo root.

Architecture

                              +--------------------------+
Claude Code / Codex --stdio-> |     MCP Server (TS)      |
                              |  read_console,           |
                              |  send_command,           |
                              |  skript_eval, etc.       |
                              +------------+-------------+
                                           | HTTPS (encrypted RPC)
                                           v
                              +--------------------------+
User Client (Python)          |   Intermediate Server    |
mounts files as a   --HTTPS-> |        (Node.js)         |
Windows drive (M:\)           |  Blind encrypted relay   |
                              +------------+-------------+
                                           | WebSocket
                                           v
                              +--------------------------+
                              |    Minecraft Plugin      |
                              |  (Paper 1.21+, Java 21)  |
                              +--------------------------+

Everything between the user client / MCP server and the Minecraft plugin is end-to-end encrypted with AES-256-GCM. The intermediate server only sees opaque encrypted blobs and a SHA-256 token hash, so it cannot decrypt any traffic.

Components

Folder	Language	Role
minecraft-plugin/	Java 21 (Paper 1.21+)	Plugin that runs on the MC server. Captures console, executes commands, serves files, evaluates Skript
intermediate-server/	TypeScript / Node.js	Stateless blind relay. Routes encrypted RPC requests between clients and plugins
mcp-server/	TypeScript / Node.js	MCP server that exposes tools to Claude Code and Codex over stdio
user-client/	Python (Textual TUI)	Setup TUI + WebDAV provider that mounts the server filesystem as a Windows drive
build.py	Python	Bundles everything into a single portable dist/mcclaude.py

Security model

• The user types a token once; the client stores it in %APPDATA%/mcclaude/config.json
• Clients send SHA-256(token) as X-Token-Hash to authenticate with the relay, so the raw token never leaves the user's machine
• The encryption key is derived from SHA-256(token). The Minecraft plugin holds the same token in its config, so both sides can encrypt/decrypt
• The intermediate server stores nothing. It routes opaque encrypted blobs by token hash

Development

# Plugin
cd minecraft-plugin && ./gradlew shadowJar

# MCP server (dev)
cd mcp-server && npm install && npm run dev

# Intermediate server (dev)
cd intermediate-server && npm install && npm run dev

# Bundle the user client
python build.py

# Install client dependencies and run its tests (Windows)
pip install -r dist/requirements.txt
python -m unittest discover -s tests -v

A note on AI assistance

McClaude was built with substantial help from Claude (the AI). Most of the code was AI-generated and then iterated on. If you spot something weird, awkwardly named, or over-engineered, that's likely why.

Contributing

PRs are welcome. Whether it's bug fixes, new MCP tools, plugin compatibility notes, deployment guides, or refactoring questionable AI choices, open an issue or send a pull request.

License

MIT, see LICENSE.