{"id":31789301,"url":"https://github.com/aternosorg/mc-server-management","last_synced_at":"2026-04-28T19:00:44.267Z","repository":{"id":314893579,"uuid":"1057225268","full_name":"aternosorg/mc-server-management","owner":"aternosorg","description":"A library for the Minecraft server management protocol added in 25w35a","archived":false,"fork":false,"pushed_at":"2026-04-28T17:04:16.000Z","size":297,"stargazers_count":17,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-28T17:24:44.363Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/mc-server-management","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aternosorg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-15T12:48:18.000Z","updated_at":"2026-04-28T17:04:20.000Z","dependencies_parsed_at":"2025-09-15T14:01:56.414Z","dependency_job_id":"3101ff85-4a79-4281-9a32-8962d4effbef","html_url":"https://github.com/aternosorg/mc-server-management","commit_stats":null,"previous_names":["aternosorg/mc-server-management"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/aternosorg/mc-server-management","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fmc-server-management","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fmc-server-management/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fmc-server-management/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fmc-server-management/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aternosorg","download_url":"https://codeload.github.com/aternosorg/mc-server-management/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fmc-server-management/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32394478,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T14:34:11.604Z","status":"ssl_error","status_checked_at":"2026-04-28T14:32:37.009Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T14:50:43.309Z","updated_at":"2026-04-28T19:00:44.260Z","avatar_url":"https://github.com/aternosorg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minecraft Server Management Protocol Client\n\n## About\n\nThis is a TypeScript/JavaScript client library for the Minecraft server management protocol added in 1.21.9.\n\n## Features\n\n- Complete type definitions\n- Builders for all request parameters\n- Full API coverage (including Notifications)\n- Authentication support\n- Promise-based API\n- Automatic reconnection\n- TLS support\n- Connection interface for custom transports (e.g. proxying over a different connection)\n- Custom error classes for errors returned by the server\n- Type validation of responses\n- ESModule and CommonJS support\n- Supports establishing connections from a web browser or Node.js environment\n\n## Requirements\n\n- Minecraft 1.21.9-pre4 or later.\n- Node 22+ or another ES2022+ compatible environment.\n\n## Installation\n\nYou can install the library using npm:\n```shell\nnpm install mc-server-management\n```\n\n## Setting up the Minecraft Server\nTo enable the management protocol set `management-server-enabled`, `management-server-port` and `management-server-host`\nin the server.properties file:\n```properties\nmanagement-server-enabled=true\nmanagement-server-port=25585\nmanagement-server-host=0.0.0.0\nmanagement-server-secret=\n```\nYou can either set `management-server-secret` to a random 40 character long alphanumeric string or leave it empty and\nlet the Minecraft server generate a random token on startup. You will need this token to connect to the server.\n\nIf you want to establish connections from a web browser, you need to set the allowed origins:\n```properties\nmanagement-server-allowed-origins=http\\://localhost\\:63315\n```\n\n### TLS\nBy default, TLS is enabled, but the server will crash if you don't provide a certificate. If the management protocol is\nnot exposed to the internet, or you are using a reverse proxy, the easiest option would be to disable TLS:\n```properties\nmanagement-server-tls-enabled=false\n```\n\n#### Using a custom certificate\nIf you want to use TLS, you need to provide a PKCS12 keystore file containing the certificate. To convert an existing\ncertificate and private key to a PKCS12 file you can use OpenSSL:\n```shell\nopenssl pkcs12 -export -in cert.pem -inkey key.pem -out keystore.p12\n```\n\n#### Creating a self-signed certificate\nTo create untrusted local certificates use a tool like [mkcert](https://github.com/FiloSottile/mkcert). You will need to\ntell npm to trust the root CA created by mkcert using the `NODE_EXTRA_CA_CERTS` environment variable:\n```shell\nmkcert -pkcs12 localhost\nexport NODE_EXTRA_CA_CERTS=\"$(mkcert -CAROOT)/rootCA.pem\"\n```\n\n#### Setting up the keystore\nThen set the path to the keystore file and the password in the server.properties file:\n```properties\nmanagement-server-tls-keystore=keystore.p12\nmanagement-server-tls-keystore-password=changeit\n```\n\n## Usage\n\nThis library can be used as an ES or CommonJS module.\n```typescript\n// ESM\nimport {WebsocketConnection, MinecraftServer} from 'mc-server-management';\n// CJS\nconst {WebsocketConnection, MinecraftServer} = require('mc-server-management');\n```\n\n### Creating a Connection\n\nThe simplest way to create a connection is using the static `connect` method on `WebSocketConnection`. All you need is\nthe URL to connect to and the authentication token. The token can be found in the server.properties file of your\nMinecraft server.\n```typescript\nconst connection = await WebSocketConnection.connect(\"wss://\u003cyour-server\u003e:\u003cmanagement-port\u003e\", \"\u003cauth-token\u003e\");\n```\n\nWebSocketConnection is automatically exported to have the correct WebSocket implementation for your environment\n(Node.js or browser).\n\n### Creating a MinecraftServer Instance\n\nThe MinecraftServer class is the main entry point for interacting with the server. You can create an instance\nby passing in a connection.\n```typescript\nconst server = new MinecraftServer(connection);\n```\n\n### Getting the Server Status\n\n```typescript\nconst status = await server.getStatus();\nconsole.log(`Server is ${status.started ? \"running\" : \"starting\"} on version ${status.version.name} with ${status.players.length} players.`);\n// getStatus inteliigently caches the result. It is automatically updated when the server sends a notification and only\n// fetched if it has not yet been cached or you use the force option.\n\n// Get just the player list. This method is cached and automatically updated using notifications.\nconst players = await server.getConnectedPlayers();\n```\n\n### Kicking Players\n\n```typescript\n// Kick a player by their username\nawait server.kickPlayers(\"Aternos\");\n// You can also kick multiple players at once. To identify a player by their UUID, not username use `Player.withId(uuid)`.\nawait server.kickPlayers([Player.withName(\"Aternos\"), Player.withId(\"player-uuid\")]);\n// Specifying a message is optional\nawait server.kickPlayers(Player.withName(\"Aternos\"), \"You have been kicked!\");\n// You can also use a Message object, either for a literal or translated message\nawait server.kickPlayers(Player.withName(\"Aternos\"), Message.literal(\"You have been kicked!\"));\nawait server.kickPlayers(Player.withName(\"Aternos\"), Message.translatable(\"test.translation.key\", [\"arg1\", \"arg2\"]));\n```\n\n### Saving and Stopping the Server\n\n```typescript\n// Save the server\nawait server.save();\n\n// Stop the server\nawait server.stop();\n```\n\n### Sending Chat Messages\n\n```typescript\n// Send a system message to all players in the chat\nawait server.sendSystemMessage(\"Hello World!\");\n// Send a system message to specific players in the chat\nawait server.sendSystemMessage(\"Hello World!\", \"Aternos\");\nawait server.sendSystemMessage(\"Hello World!\", [\"Aternos\", Player.withId(\"player-uuid\")]);\n// Show the message as an overlay above the hotbar for all players\nawait server.sendSystemMessage(\"Hello World!\", \"Aternos\", true);\n```\n\n### Querying and Updating Game Rules\n\n```typescript\n// Get all gamerules. This method is cached and automatically updated using notifications.\nconst gamerules = await server.getGameRules();\nconsole.log(gamerules);\n\n// Update a gamerule\nawait server.updateGameRule(\"minecraft:advance_time\", true);\n\n// Before 1.21.11 gamerule names are camelCase and have no namespace prefix. Use server.hasGameRulesRegistry() to\n// check which format to use.\n```\n\n### The Allowlist\n\n```typescript\n// Get an API wrapper for the allowlist (aka whitelist)\nconst allowlist = server.allowlist();\n\n// Get all players from the allowlist. This method is cached and automatically updated using notifications.\nconst allowedPlayers = await allowlist.get();\nconsole.log(allowedPlayers);\n\n// Add a player to the allowlist\nawait allowlist.add(\"Aternos\");\nawait allowlist.add(Player.withName(\"Aternos\"));\nawait allowlist.add([\"Aternos\", Player.withId(\"player-uuid\")]);\n\n// Remove a player from the allowlist\nawait allowlist.remove(Player.withId(\"player-uuid\"));\n\n// Set the entire allowlist\nawait allowlist.set([\"Aternos\", Player.withId(\"player-uuid\")]);\n\n// Clear the allowlist\nawait allowlist.clear();\n```\n\n### Operators\n\n```typescript\n// Get an API wrapper for the operators\nconst ops = server.operatorList();\n\n// Get all operators. This method is cached and automatically updated using notifications.\nconst operators = await ops.get();\nconsole.log(operators);\n\n// Add an operator\nawait ops.add(\"Aternos\");\n// Optionally specify the operator level and whether they bypass the player limit\nawait ops.add(\"Aternos\", 4, true);\nawait ops.add(Player.withId(\"player-uuid\"), 2, false);\nawait ops.add([\"Aternos\", Player.withId(\"player-uuid\")], 3, true);\n\n// Remove an operator\nawait ops.remove(\"Aternos\");\nawait ops.remove(Player.withId(\"player-uuid\"));\nawait ops.remove([\"Aternos\", Player.withId(\"player-uuid\")]);\n\n// Set the entire operator list\nawait ops.set([\"Aternos\", Player.withId(\"player-uuid\")]);\n// You can specify the permission level and whether they bypass the player limit for each operator\n// The default level and bypass options are only used for string/Player entries\nawait ops.set(\n    [\n        new Operator(\"Aternos\", 4, true), // Aternos with level 4 and bypass\n        new Operator(Player.withId(\"player-uuid\"), 2, false), // player-uuid with level 2 and no bypass\n        \"Aternos\", // Aternos with level 3 and bypass\n    ],\n    3,\n    true,\n);\n\n// Clear the operator list\nawait ops.clear();\n```\n\n### Bans\n\n```typescript\n// Get an API wrapper for the bans\nconst bans = server.banList();\n\n// Get all bans. This method is cached and automatically updated using notifications.\nconst banList = await bans.get();\nconsole.log(banList);\n\n// Ban a player by their username or UUID. You can optionally specify a reason, source and when the ban expires.\nawait bans.add(\"Aternos\");\nawait bans.add(Player.withId(\"player-uuid\"), \"Breaking the rules\", \"Source\", new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)); // Expires in 7 days\n// The optional fields are only used for input objects that aren't already ban objects.\nawait bans.add([\n    \"Aternos\", // Expires in 1 day\n    Player.withId(\"player-uuid\"), // Expires in 1 day\n    new UserBan(\"Notch\"), // Never expires\n], \"Breaking the rules\", \"Source\", new Date(Date.now() + 24 * 60 * 60 * 1000));\n\n// Unban a player by their username or UUID\nawait bans.remove(\"Aternos\");\nawait bans.remove(Player.withId(\"player-uuid\"));\nawait bans.remove([\n    \"Aternos\",\n    Player.withId(\"player-uuid\"),\n]);\n\n// Set the entire ban list at once. This will add new bans and remove old ones.\nawait bans.set([\n    new UserBan(\"Notch\"),\n    Player.withId(\"player-uuid\"),\n]);\n\n// Clear the entire ban list\nawait bans.clear();\n```\n\n### IP Bans\n\n```typescript\n// Get an API wrapper for the IP bans\nconst ipBans = server.ipBanList();\n\n// Get all IP bans. This method is cached and automatically updated using notifications.\nconst ipBanList = await ipBans.get();\nconsole.log(ipBanList);\n\n// Ban an IP address. You can optionally specify a reason, source and when the ban expires.\nawait ipBans.add(\"192.168.1.100\");\nawait ipBans.add(\"10.0.0.5\", \"Suspicious activity\", \"Admin\", new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)); // Expires in 7 days\nawait ipBans.add([\n    \"192.168.1.101\", // Expires in 1 day\n    \"10.0.0.6\",      // Expires in 1 day\n    IncomingIPBan.withIp(\"172.16.0.1\"), // Never expires\n], \"Malicious behavior\", \"Moderator\", new Date(Date.now() + 24 * 60 * 60 * 1000));\n\n// Unban an IP address\nawait ipBans.remove(\"192.168.1.100\");\nawait ipBans.remove(\"10.0.0.5\");\nawait ipBans.remove([\n    \"192.168.1.101\",\n    \"10.0.0.6\",\n]);\n\n// Set the entire IP ban list at once. This will add new bans and remove old ones.\nawait ipBans.set([\n    new IPBan(\"172.16.0.1\"),\n    \"10.0.0.5\",\n]);\n\n// Clear the entire IP ban list\nawait ipBans.clear();\n```\n\n\n### Get/Update server settings\n\n```typescript\n// Get an API wrapper for the server settings\nconst settings = server.settings();\n\nconst acceptTransfers = await settings.getAcceptTransfers()\nawait settings.setAcceptTransfers(!acceptTransfers);\n```\n\nFor a list of all available settings, see the `ServerSettings` class.\n\n### Events / Notifications\n\nThe Minecraft server sends events as so called `Notifications`. You can listen for these events using the `on` method.\nFor a list of all available notifications, see the `Notifications` enum.\n\n```typescript\n// Subscribe to notifications\nserver.on(Notifications.SERVER_SAVED, () =\u003e console.log(\"Server saved!\"));\n\n// Notifications with data\nserver.on(Notifications.GAME_RULE_UPDATED, data =\u003e console.log(`Game rule ${data.key} updated to ${data.value}`));\n\n// Listen for errors\nserver.on('error', error =\u003e console.error(\"Error:\", error));\n\n// Only listen for a notification once\nserver.once(Notifications.SERVER_STARTED, () =\u003e {\n    console.log(\"Server started!\");\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fmc-server-management","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faternosorg%2Fmc-server-management","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fmc-server-management/lists"}