Minecraft:Minecraft Server Management Protocol

Template:Wip Template:Exclusive Minecraft Server Management Protocol is a server management API (JSON-RPC over WebSocket) for dedicated servers.

Access

The API is disabled by default and can be enabled in the Minecraft:server.properties file. A server-specific secret can be configured using the management-server-secret property. Clients must authenticate to access the API by providing this secret in one of two ways:

• In the Authorization header as a bearer token containing the secret (ex. Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmo)
• In the Sec-WebSocket-Protocol header following the string minecraft-v1, (ex. Sec-WebSocket-Protocol: minecraft-v1,ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmo). This enables use via the web as this header is populated by the JavaScript WebSocket constructor.

server.properties name	Default	Description
management-server-allowed-origins	None	Comma separated list of the origins allowed to connect to the server. Requests will be rejected with a 401 Unauthorized error if they do not contain an Origin HTTP header with a value in this list. If left empty, no clients will be able to connect. The origins provided do not have to be valid URLs/domains.
management-server-enabled	false	Set to true to enable the API
management-server-host	localhost	Host of the API endpoint
management-server-port	0	Port of the API endpoint. Defaults to 0, assigning a random port on startup. Can be changed to a static port.
management-server-secret	If empty on startup a value is generated and written to Minecraft:server.properties	The secret should be exactly 40 alphanumeric characters (A-Z, a-z, 0-9). The secret will be automatically generated if the server property is empty. Unauthorized requests are rejected with 401 Unauthorized.
management-server-tls-enabled	true	Can be set to false to disable TLS. Requires a keystore file to be configured, see management-server-tls-keystore
management-server-tls-keystore	None	The keystore file must be in PKCS12 format
management-server-tls-keystore-password	None	Keystore password can be set in the following ways, in order of priority Environment variable: MINECRAFT_MANAGEMENT_TLS_KEYSTORE_PASSWORD JVM argument: -Dmanagement.tls.keystore.password= Server property: management-server-tls-keystore-password=

The API is accessible at ws://<management-server-host>:<management-server-port> when enabled. It uses the WebSocket protocol and adheres to JSON-RPC 2.0 specification.

An example command for creating a compatible keystore: keytool -genkeypair -alias testkey -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore test-keystore.p12 -validity 3650

Methods

Allowlist

Endpoints are accessible at minecraft:allowlist

Path	Description	Parameters	Result
/	Get the allowlist	None	allowlist: Array<Player>
/set	Set the allowlist to the provided list of players	players: Array<Player>	allowlist: Array<Player>
/add	Add players to the allowlist	add: Array<Player>	allowlist: Array<Player>
/remove	Remove players from allowlist	remove: Array<Player>	allowlist: Array<Player>
/clear	Clear all players in allowlist	None	allowlist: Array<Player>

Bans

Endpoints are accessible at minecraft:bans

Path	Description	Parameters	Result
/	Get the ban list	None	banlist: Array<User Ban>
/set	Set the banlist	bans: Array<User Ban>	banlist: Array<User Ban>
/add	Add players to the ban list	add: Array<User Ban>	banlist: Array<User Ban>
/remove	Remove players from ban list	remove: Array<Player>	banlist: Array<User Ban>
/clear	Clear all players in ban list	None	banlist: Array<User Ban>

IP Bans

Endpoints are accessible at minecraft:ip_bans

Path	Description	Parameters	Result
/	Get the ip ban list	None	banlist: Array<IP Ban>
/set	Set the ip banlist	banlist: Array<IP Ban>	banlist: Array<IP Ban>
/add	Add ip to ban list	add: Array<Incoming IP Ban>	banlist: Array<IP Ban>
/remove	Remove ip from ban list	ip: Array<string>	banlist: Array<IP Ban>
/clear	Clear all ips in ban list	None	banlist: Array<IP Ban>

Players

Endpoints are accessible at minecraft:players

Path	Description	Parameters	Result
/	Get all connected players	None	players: Array<Player>
/kick	Kick players	kick: Array<Kick Player>	kicked: Array<Player>

Operators

Endpoints are accessible at minecraft:operators

Path	Description	Parameters	Result
/	Get all oped players	None	operators: Array<Operator>
/set	Set all oped players	operators: Array<Operator>	operators: Array<Operator>
/add	Op players	add: Array<Operator>	operators: Array<Operator>
/remove	Deop players	remove: Array<Player>	operators: Array<Operator>
/clear	Deop all players	None	operators: Array<Operator>

Server

Endpoints are accessible at minecraft:server

Path	Description	Parameters	Result
/status	Get server status	None	status: Server State
/save	Save server state	flush: boolean	saving: boolean
/stop	Stop server	None	stopping: boolean
/system_message	Send a system message	message: System Message	sent: boolean

Server Settings

Endpoints are accessible at minecraft:serversettings

Path	Description	Parameters	Result
/autosave	Get whether automatic world saving is enabled on the server	None	enabled: boolean
/autosave/set	Enable or disable automatic world saving on the server	enable: boolean	enabled: boolean
/difficulty	Get the current difficulty level of the server	None	difficulty: Difficulty
/difficulty/set	Set the difficulty level of the server	difficulty: Difficulty	difficulty: Difficulty
/enforce_allowlist	Get whether allowlist enforcement is enabled (kicks players immediately when removed from allowlist)	None	enforced: boolean
/enforce_allowlist/set	Enable or disable allowlist enforcement (when enabled, players are kicked immediately upon removal from allowlist)	enforce: boolean	enforced: boolean
/use_allowlist	Get whether the allowlist is enabled on the server	None	used: boolean
/use_allowlist/set	Enable or disable the allowlist on the server (controls whether only allowlisted players can join)	use: boolean	used: boolean
/max_players	Get the maximum number of players allowed to connect to the server	None	max: integer
/max_players/set	Set the maximum number of players allowed to connect to the server	max: integer	max: integer
/pause_when_empty_seconds	Get the number of seconds before the game is automatically paused when no players are online	None	seconds: integer
/pause_when_empty_seconds/set	Set the number of seconds before the game is automatically paused when no players are online	seconds: integer	seconds: integer
/player_idle_timeout	Get the number of seconds before idle players are automatically kicked from the server	None	seconds: integer
/player_idle_timeout/set	Set the number of seconds before idle players are automatically kicked from the server	seconds: integer	seconds: integer
/allow_flight	Get whether flight is allowed for players in Survival mode	None	allowed: boolean
/allow_flight/set	Set whether flight is allowed for players in Survival mode	allowed: boolean	allowed: boolean
/motd	Get the server's message of the day displayed to players	None	message: string
/motd/set	Set the server's message of the day displayed to players	message: string	message: string
/spawn_protection_radius	Get the spawn protection radius in blocks (only operators can edit within this area)	None	radius: integer
/spawn_protection_radius/set	Set the spawn protection radius in blocks (only operators can edit within this area)	radius: integer	radius: integer
/force_game_mode	Get whether players are forced to use the server's default game mode	None	forced: boolean
/force_game_mode/set	Set whether players are forced to use the server's default game mode	force: boolean	forced: boolean
/game_mode	Get the server's default game mode	None	mode: Game Mode
/game_mode/set	Set the server's default game mode	mode: Game Mode	mode: Game Mode
/view_distance	Get the server's view distance in chunks	None	distance: integer
/view_distance/set	Set the server's view distance in chunks	distance: integer	distance: integer
/simulation_distance	Get the server's simulation distance in chunks	None	distance: integer
/simulation_distance/set	Set the server's simulation distance in chunks	distance: integer	distance: integer
/accept_transfers	Get whether the server accepts player transfers from other servers	None	accepted: boolean
/accept_transfers/set	Set whether the server accepts player transfers from other servers	accept: boolean	accepted: boolean
/status_heartbeat_interval	Get the interval in seconds between server status heartbeats	None	seconds: integer
/status_heartbeat_interval/set	Set the interval in seconds between server status heartbeats	seconds: integer	seconds: integer
/operator_user_permission_level	Get the permission level required for operator commands	None	level: integer
/operator_user_permission_level/set	Set the permission level required for operator commands	level: integer	level: integer
/hide_online_players	Get whether the server hides online player information from status queries	None	hidden: boolean
/hide_online_players/set	Set whether the server hides online player information from status queries	hide: boolean	hidden: boolean
/status_replies	Get whether the server responds to connection status requests	None	enabled: boolean
/status_replies/set	Set whether the server responds to connection status requests	enable: boolean	enabled: boolean
/entity_broadcast_range	Get the entity broadcast range as a percentage	None	percentage_points: integer
/entity_broadcast_range/set	Set the entity broadcast range as a percentage	percentage_points: integer	percentage_points: integer

Gamerules

Endpoints are accessible at minecraft:gamerules

Path	Description	Parameters	Result
/	Get the available game rule keys and their current values	None	gamerules: Array<Typed Game Rule>
/update	Update game rule value	gamerule: Untyped Game Rule	gamerule: Typed Game Rule

Notifications

Server

Endpoints are accessible at minecraft:notification/server

Path	Description	Parameters
/started	Server started	None
/stopping	Server shutting down	None
/saving	Server save started	None
/saved	Server save completed	None
/status	Server status heartbeat	status: Server State
/activity	Network connection initialized	None

Players

Endpoints are accessible at minecraft:notification/players

Path	Description	Parameters
/joined	Player joined	player: Player
/left	Player left	player: Player

Operators

Endpoints are accessible at minecraft:notification/operators

Path	Description	Parameters
/added	Player was oped	player: Operator
/removed	Player was deoped	player: Operator

Allowlist

Endpoints are accessible at minecraft:notification/allowlist

Path	Description	Parameters
/added	Player was added to the allowlist	player: Player
/removed	Player was removed from allowlist	player: Player

IP Bans

Endpoints are accessible at minecraft:notification/ip_bans

Path	Description	Parameters
/added	Ip was added to ip ban list	player: IP Ban
/removed	Ip was removed from ip ban list	player: string

Bans

Endpoints are accessible at minecraft:notification/bans

Path	Description	Parameters
/added	Player was added to the ban list	player: User Ban
/removed	Player was removed from the ban list	player: Player

Gamerules

Endpoints are accessible at minecraft:notification/gamerules

Path	Description	Parameters
/updated	Gamerule was changed	gamerule: Typed Game Rule

WorldTemplate:Upcoming

Endpoints are accessible at minecraft:notification/world

Path	Description	Parameters
/upgrade_started	World upgrade started	None
/upgrade_progress	World upgrade progress. Rate limited to 1 notification per second	progress: number between 0 and 1
/upgrade_finished	World upgrade finished	None
/upgrade_failed	World upgrade failed	reason: string

Schemas

Difficulty

• • Template:Nbt: The Minecraft:difficulty, either Template:Cd.

Game Mode

• • Template:Nbt: The Minecraft:game mode, either Template:Cd.

ISO-8601 Instant

• • Template:Nbt: An ISO-8601 timestamp that specifies date, time, and timezone offset. Specifically, the format parsed by Java's Template:Cd. For example, Template:Cd.

Incoming IP Ban

• Template:Nbt An incoming IP ban. At least one of Template:Nbt or Template:Nbt must be present.
  • Template:Nbt: (Optional) IP address to ban. If not present or not a valid IP address, falls back to Template:Nbt.
  • Template:Nbt: (Optional) Player. This player's IP is used if Template:Nbt isn't valid.
  • Template:Nbt: (Optional) Explanation of why the IP was banned, for display to banned players.
  • Template:Nbt: (Optional) Description of the source of the ban. Defaults to Template:Cd. For bans created with Template:Cmd, this would be the name of the command executor.
  • Template:Nbt: (Optional) ISO-8601 Instant. If not present, the ban will never expire.

IP Ban

• Template:Nbt An IP ban.
  • Template:Nbt: The IP address that is banned.
  • Template:Nbt: (Optional) Explanation of why the IP was banned, for display to banned players.
  • Template:Nbt: (Optional) Description of the source of the ban. Defaults to Template:Cd. For bans created with Template:Cmd, this would be the name of the command executor.
  • Template:Nbt: (Optional) ISO-8601 Instant. If not present, the ban will never expire.

Kick Player

• Template:Nbt A kick player request.
  • Template:Nbt: Player. The player to kick.
  • Template:Nbt: (Optional) Message. Explanation of why the player was kicked, displayed to the kicked player.

Message

• Template:Nbt A display message that supports translation. If neither Template:Nbt nor Template:Nbt are present, there is no message.
  • Template:Nbt: (Optional) The Minecraft:translation key to display. If not present, Template:Nbt is displayed instead.
  • Template:Nbt: (Optional) An array of strings to be inserted into the slots of the translation.
  • Template:Nbt: (Optional) The untranslated message to display if Template:Nbt is not present.

Operator

• Template:Nbt A server Minecraft:operator.
  • Template:Nbt: Player.
  • Template:Nbt: (Optional) The Minecraft:permission level that the operator has. Defaults to the default operator permission level.
  • Template:Nbt: (Optional) Whether this player can join the server even while the number of players online has reached the limit set by [[Minecraft:Server.properties#max-players|the Template:Cd property]]. Defaults to the player's current Template:Nbt if they are already an operator, or Template:Cd if they are not.

Player

• Template:Nbt A player specifier. If neither Template:Nbt nor Template:Nbt are present, this will fail to select any player.
  • Template:Nbt: (Optional) The player's Minecraft:UUID in hyphenated hexadecimal form. If not present, falls back to using Template:Nbt.
  • Template:Nbt: (Optional) The player's name. Used for selection if Template:Nbt is not present.

Server State

• Template:Nbt The current state of the server.
  • Template:Nbt: Template:Cd if the server has started, otherwise Template:Cd.
  • Template:Nbt: Array<Player>. List of players that are currently online.
  • Template:Nbt: Version. Version of the server.

System Message

• Template:Nbt A server message.
  • Template:Nbt: Message. The message to display.
  • Template:Nbt: If Template:Cd, the message is displayed in chat. If Template:Cd, the message is displayed in the Minecraft:action bar.
  • Template:Nbt: (Optional) Array<Player>. List of players to send the message to. Defaults to all players.

Typed Game Rule

• Template:Nbt A Minecraft:game rule with a specified type.
  • Template:Nbt: The Minecraft:resource ID of the game rule.
  • Template:Nbt: The type of the game rule. Either Template:Cd or Template:Cd.
  • Template:NbtTemplate:NbtTemplate:Nbt: The value of the game rule. The server will always output an Template:Nbt integer or Template:Nbt boolean, as appropriate. Integers can be parsed from Template:Nbt strings, but booleans can not.

Untyped Game Rule

• Template:Nbt A Minecraft:game rule of unspecified type.
  • Template:Nbt: The Minecraft:resource ID of the game rule.
  • Template:NbtTemplate:NbtTemplate:Nbt: The value of the game rule. Integers can be parsed from Template:Nbt strings, but booleans can not.

User Ban

• Template:Nbt A user ban.
  • Template:Nbt: Player.
  • Template:Nbt: (Optional) Explanation of why the player was banned, for display to banned players.
  • Template:Nbt: (Optional) Description of the source of the ban. Defaults to Template:Cd. For bans created with Template:Cmd, this would be the name of the command executor.
  • Template:Nbt: (Optional) ISO-8601 Instant. If not present, the ban will never expire.

Version

• Template:Nbt A Minecraft version identifier.
  • Template:Nbt: The name of the version.
  • Template:Nbt: The Minecraft:protocol version ID.

Notes

• Supports querying and updating of server state (players, allowlist, operators, settings, game rules).
• Sends notifications on state changes (e.g. player joins, game rule updates).
• Calling {"jsonrpc":"2.0","method":"rpc.discover","id":1} returns an API schema containing supported methods and notifications of the currently running server.
• The Data Generator produces an API schema (json-rpc-api-schema.json) in the reports output folder mirroring the contents returned by the rpc.discover method.
• The API adheres to the JSON-RPC 2.0 specification.
• Uses namespaced methods and the reserved namespace is minecraft (e.g. minecraft:players, minecraft:allowlist/add, minecraft:notification/players/joined).
  • Extensible via custom namespaces for additional methods and events.
• Core method groups: players, allowlist, operators, server (save, stop), server settings, game rules.
• Example method call:
  • Request: {"method":"minecraft:allowlist/add","id":1,"params":[[Minecraft:{"name":"jeb_"}]]}
  • Response: {"jsonrpc":"2.0","id":1,"result":[{"id":"853c80ef-3c37-49fd-aa49-938b674adae6","name":"jeb_"}]}
• Example notification:
  • {"jsonrpc":"2.0","method":"minecraft:notification/players/joined","params":[{"id":"853c80ef-3c37-49fd-aa49-938b674adae6","name":"jeb_"}]}
• Example error:
  • Request: {"method": "minecraft:foo/bar","id": 1}
  • Response: {"jsonrpc":"2.0","id":1,"result":{"jsonrpc":"2.0","id":1,"error":{"code":-32601,"message":"Method not found","data":"Method not found: minecraft:foo/bar"}}}
  • Errors and error codes follow JSON-RPC 2.0 error object format.

Example implementations

• https://github.com/Aliorpse/mcutils (client, Kotlin Multiplatform)
• https://github.com/TechnoBro03/MC-SMP (client, Python)