@rcon-sdk/minecraft

A TypeScript SDK for controlling Minecraft servers via RCON. Built because I got tired of writing raw command strings and wanted proper autocomplete.

Why this exists

Minecraft's RCON protocol is straightforward, but building command strings manually is error-prone. This SDK gives you:

• Type-safe command builders - Stop guessing parameter order
• Connection pooling - For bots and high-traffic tools
• Zero dependencies - Just Node.js built-ins

Installation

npm install @rcon-sdk/minecraft

Quick start

import { createRCON, commands } from '@rcon-sdk/minecraft';

const client = createRCON({
  host: 'localhost',
  port: 25575,
  password: 'your-rcon-password'
});

await client.connect();

// Execute raw commands
await client.exec('say Hello World');

// Or use the builder
const give = commands.give()
  .player('Notch')
  .item('minecraft:diamond')
  .amount(64);

await client.exec(give.build());

Command builders

Instead of string concatenation:

// Bad
await client.exec(`give ${player} ${item} ${amount}`);

// Good
await client.exec(
  commands.give()
    .player(player)
    .item(item)
    .amount(amount)
    .build()
);

Available builders: give, time, weather, gamemode, say, tellraw, title, kill, teleport, effect, difficulty, spawnpoint, setworldspawn, scoreboard, me, msg, team.

Each returns the command string - you still call client.exec() to run it.

Connection pooling

For servers handling many commands:

const client = createRCON({
  host: 'localhost',
  port: 25575,
  password: 'password',
  pool: {
    min: 2,
    max: 10
  }
});

Error handling

try {
  await client.exec('invalid command');
} catch (err) {
  if (err.code === 'COMMAND_FAILED') {
    // Command rejected by server
  }
}

Requirements

• Node.js 18+
• Minecraft server with RCON enabled (enable-rcon=true in server.properties)

License

MIT