# MineCode MCP
**Version-accurate Minecraft data for AI assistants**
[](https://pypi.org/project/minecode-mcp/)
[](https://python.org)
[](LICENSE)
[](https://github.com/AnCarsenat/minecode-mcp/actions/workflows/test.yml)
[](https://mseep.ai/app/ancarsenat-minecode-mcp)
[](https://mseep.ai/app/5b3391b1-6799-4fd5-8496-308849e8a8c7)
MineCode is a **local** [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants like **GitHub Copilot** and **Claude** real-time access to version-accurate Minecraft data, documentation, vanilla presets, and your Minecraft logs.
Written for a hackathon about MCP sponsored by dust, alpic, and others. Prototyped using the worst ai model ;-; (note I rewrote it now it is actually viable). Please star if you'd like to help out, and open issues for anything broken.
---
## π― The problem this solves
AI assistants get Minecraft syntax wrong constantly, and they do it *confidently*. The reason is simple: Minecraft's datapack format changed substantially and repeatedly, and every model's training data is older than the current game.
- **1.20.5** replaced item NBT with typed components. Old NBT is now a hard parse error.
- **1.21** renamed every datapack folder to singular (`advancements/` β `advancement/`). A pack with the old names loads with **no error and no content** β it silently does nothing.
- **1.21.2** dropped the `generic.` prefix from every attribute ID.
- **1.21.4** turned `custom_model_data` from an integer into an object.
- **1.21.5** made text components strictly typed.
minecraft.wiki documents **only the latest version**, so consulting it for an older pack actively makes this worse.
MineCode attacks this from four directions:
1. **`minecraft_start_session`** β detects the target version from `pack.mcmeta` before any code is written, so nothing downstream is guessing.
2. **`get_technical_changes`** β returns what actually changed between two versions, from [misode/technical-changes](https://github.com/misode/technical-changes) plus a curated table of the traps agents fall into most.
3. **`get_command_usage` / `validate_command`** β command syntax compiled from the game's own Brigadier grammar, and a parser to check the agent's output against it.
4. **Honest tool descriptions** β every wiki tool states up front that it covers the latest version only, and names the version-exact alternative.
---
## π Installation
**Requires Python 3.10 or newer.** Check with `python --version` (Windows: `py --version`).
### Windows
```powershell
py -m pip install --upgrade pip
py -m pip install minecode-mcp
```
Verify:
```powershell
py -m minecode.server --help 2>$null; py -c "import minecode; print('ok')"
```
> **If `py` is not recognised:** Python isn't installed or wasn't added to PATH. Reinstall from [python.org](https://python.org/downloads/) with **"Add python.exe to PATH"** ticked. Avoid the Microsoft Store build β it sandboxes file access, which breaks reading `pack.mcmeta` and Minecraft logs from arbitrary paths.
### macOS
```bash
python3 -m pip install --upgrade pip
python3 -m pip install minecode-mcp
```
If your Python is Homebrew-managed you'll hit `error: externally-managed-environment`. Use a venv (see below) or `pipx`:
```bash
brew install pipx && pipx install minecode-mcp
```
### Linux
```bash
python3 -m pip install --upgrade pip
python3 -m pip install minecode-mcp
```
Most modern distributions (Arch, Debian 12+, Ubuntu 23.04+, Fedora) mark the system Python as externally managed and will refuse the command above. That protection is correct β don't override it with `--break-system-packages`. Use one of:
```bash
# Option A: pipx β recommended, isolated but still on PATH
sudo pacman -S python-pipx # Arch
sudo apt install pipx # Debian/Ubuntu
sudo dnf install pipx # Fedora
pipx install minecode-mcp
# Option B: user install
python3 -m pip install --user minecode-mcp
# Option C: a venv you point the client at (see Configuration)
```
### Isolated install (any platform)
Works everywhere and never touches system Python. **Note the absolute path it prints** β you'll need it for the client config.
```bash
# Linux / macOS
python3 -m venv ~/.minecode-venv
~/.minecode-venv/bin/pip install minecode-mcp
echo ~/.minecode-venv/bin/minecode
```
```powershell
# Windows
py -m venv $HOME\.minecode-venv
& $HOME\.minecode-venv\Scripts\pip.exe install minecode-mcp
Write-Output "$HOME\.minecode-venv\Scripts\minecode.exe"
```
### Upgrading and uninstalling
```bash
pip install --upgrade minecode-mcp # or: pipx upgrade minecode-mcp
pip uninstall minecode-mcp # or: pipx uninstall minecode-mcp
```
Upgrading doesn't clear the response cache. That's intentional β version-pinned data can't go stale. To clear it anyway, call the `cache_status` tool with `clear=true`, or delete the directory shown by `cache_status`.
### Which Python am I actually using?
The single most common setup failure is installing into one interpreter and pointing the client at another. When in doubt, get the absolute path and use it verbatim in your client config:
```bash
python3 -c "import sys; print(sys.executable)" # Linux/macOS
py -c "import sys; print(sys.executable)" # Windows
```
---
## βΆοΈ Running the server
MineCode is an **MCP server**, not an app you sit in front of. It speaks JSON-RPC over stdin/stdout and is normally launched *by* your AI client, not by you. You rarely need to start it manually β but you do need to know how, because that's how you check the install before wiring up a client.
### The two ways to launch it
```bash
minecode # console script, installed by pip
python -m minecode.server # module form β identical, works even if the script isn't on PATH
```
On Windows use `py -m minecode.server`.
### What "working" looks like
Running it directly looks like a hang. That is correct:
```
$ minecode
[INFO] Loaded assistant preprompt from .../assistant_preprompt.txt
[INFO] Starting MineCode MCP server
[INFO] MineCode MCP server starting (stdio)
[INFO] Registered 30 tools, 1 prompts, 2 resources
```
β¦and then nothing. The server is waiting for JSON-RPC on stdin. **This is a healthy server**, not a freeze. Press `Ctrl+C` to stop it.
The line that matters is `Registered 30 tools`. If you see it, the install is good. Logs go to stderr, so they never corrupt the protocol stream on stdout.
### Verifying the install without a client
```bash
python -c "
from minecode import tools
print(f'{len(tools.TOOLS)} tools, {len(tools.HANDLERS)} handlers')
assert {t.name for t in tools.TOOLS} == set(tools.HANDLERS)
print('registry consistent')
"
```
To exercise a tool without any MCP client at all:
```bash
python -c "
from minecode import handlers
r = handlers.handle_get_command_usage('1.21.4', 'give')
print(r['usage'])
"
```
Expected: `['/give