minecraft-mcp: Instructions file for Claude Code

Instructions for Claude Code: connect to the owner's live Minecraft world

Current world

The owner is running Minecraft Java Edition 26.2 with the single-player world nz open to LAN. The live LAN server is on this same Mac at:

• host: 127.0.0.1
• port: 5056
• dimension: minecraft:overworld

The world must be open and LAN must still be enabled before connecting. Cheats are enabled by the LAN session. This is a vanilla integrated server; the repository's Paper/plugin bridge at ws://127.0.0.1:8765 is not the connection used for this world and may not be running.

Connection that is known to work

The current Mineflayer release does not negotiate this 26.2 session correctly. The verified workaround is Mineflayer 26.1 with protocol version 776 forced in the custom auth callback. Use a username of 16 characters or fewer.

From a temporary helper directory (do not add the helper or its dependencies to the repository):

mkdir -p /tmp/claude-minecraft-lan
cd /tmp/claude-minecraft-lan
npm init -y
npm install [email protected] prismarine-nbt

Create a small .mjs helper with this connection setup:

import mineflayer from 'mineflayer'

const bot = mineflayer.createBot({
  host: '127.0.0.1',
  port: 5056,
  version: '26.1',
  username: 'ClaudeLAN',
  auth: (client, options) => {
    client.username = 'ClaudeLAN'
    client.uuid = '00000000-0000-0000-0000-000000000020'
    options.auth = 'offline'
    options.protocolVersion = 776
    options.connect(client)
  }
})

const wait = ms => new Promise(resolve => setTimeout(resolve, ms))

bot.once('spawn', async () => {
  await bot.waitForChunksToLoad()
  bot.chat('/save-all flush')
  await wait(1500)
  // Work here. Commands are sent with bot.chat('/...').
})

bot.on('error', error => console.error(error.message))
bot.on('kicked', reason => console.error('KICKED', reason))

The protocol shim can emit harmless partial packet warnings while still connecting successfully. A successful spawn event is the meaningful test. If the server rejects the login with a serverbound/minecraft:hello decoder error, check that the username is at most 16 characters and that the exact version: '26.1' plus options.protocolVersion = 776 workaround is present.