Minecraft Server Management Protocol

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

The API is disabled by default and can be enabled in the 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 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

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>

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>

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>

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>

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>

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

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: string ("peaceful", "easy", "normal", "hard")
/difficulty/set	Set the difficulty level of the server	difficulty: string ("peaceful", "easy", "normal", "hard")	difficulty: string ("peaceful", "easy", "normal", "hard")
/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: string ("creative", "survival", "speactator", "adventure")
/game_mode/set	Set the server's default game mode	mode: string ("creative", "survival", "speactator", "adventure")	mode: string ("creative", "survival", "speactator", "adventure")
/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

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

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

Endpoints are accessible at minecraft:notification/players

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

Endpoints are accessible at minecraft:notification/operators

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

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

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

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

Endpoints are accessible at minecraft:notification/gamerules

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

Properties:

• value: string
• key: string

Properties:

• reason: string
• expires: string (ISO-Instant)
• ip: string
• source: string
• player: Player

Properties:

• receivingPlayers: Array<Player>
• overlay: boolean
• message: Message

Properties:

• player: Player
• message: Message

Properties:

• reason: string
• expires: string (ISO-Instant)
• ip: string
• source: string

Properties:

• type: string ("integer", "boolean")
• value: string
• key: string

Properties:

• reason: string
• expires: string (ISO-Instant)
• source: string
• player: Player

Properties:

• translatable: string
• translatableParams: Array<string>
• literal: string

Properties:

• protocol: integer
• name: string

Properties:

• players: Array<Player>
• started: boolean
• version: Version

Properties:

• permissionLevel: integer
• bypassesPlayerLimit: boolean
• player: Player

Properties:

• name: string
• id: string (UUID)

Java Edition
1.21.9			25w35a				Added the Minecraft Server Management Protocol.
			25w37a				Clients must authenticate to access the API.
							TLS is enabled by default.
			Pre-Release 1				Notifications now use minecraft:notification/ prefix instead of notification:.
1.21.11			25w41a				Is now 1.1.0.
							Added a new notification server/activity.
			25w42a				Enable authentication from web browsers.
							Added the management-server-allowed-origins field to server.properties.
			25w44a				The version is now 2.0.0.
							In the typed_game_rule and untyped_game_rule schemas, the type of the value field has been changed from string to take either a boolean or an integer.

Issues relating to "Minecraft Server Management Protocol" are maintained on the bug tracker. Issues should be reported and viewed there.

• 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 namespaces are minecraft (e.g. minecraft:players, minecraft:allowlist/add) and notification (e.g. 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":[[{"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.

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

v t e Java Edition technical
General Concepts Block entity Coordinates Crashes [String] Loot context Mob AI Point of Interest Identifier Screenshot Statistics Telemetry Tick UUID JSON General format Data values Classic Indev Pre-flattening Data component format Predicate Entity format Map item format [NBT Compound / JSON Object] NBT format Particle format Text component format § Formatting codes Key codes Random sequence Structure file format Schematic file format World Heightmap Seed Anomalous Data version Legacy Spawn chunk Level format Anvil file format Chunk format Player format Point of Interest format raids.dat format Command storage format Scoreboard format Legacy Classic level format Classic server protocol Indev level format Alpha level format Zone file format Region file format server_level.dat format villages.dat format Generated structures format .minecraft client.jar version.json client.json command_history.txt launcher_profiles.json options.txt version_manifest.json hotbar.nbt format Server list format Tools F3 Debug screen hotkey renderer Developer Tools GameTest Debug properties Obfuscation map Sound Block sound type Closed captions sounds.json Commands Brigadier Functions All commands Launching Mojang API Microsoft authentication Quick Play Legacy Legacy Minecraft authentication Yggdrasil Protocol Protocol version Packets Data types Encryption Server server.jar server.properties Server requirements Whitelist Operator list Protocols Query RCON Server Management Protocol Legacy al_version Item format
Data pack Components pack.mcmeta Pack format Advancements Functions Item modifier Loot tables Predicate Recipe Damage type Chat type Enchantment Enchantment provider Painting variant Banner pattern Instrument Jukebox song Trial spawner configuration Mob variants Dialog Armor trim Slot sources Timeline Villager trade​[upcoming JE 26.1] Trade set​[upcoming JE 26.1] World Clock​[upcoming JE 26.1] Tag Block Item Function Fluid Entity type Game event Biome Flat level generator preset World preset Structure Point of interest type Painting variant Banner pattern Instrument Damage type Enchantment Dialog Timeline Potion​[upcoming JE 26.1] Villager trade​[upcoming JE 26.1] GameTest Test environment Test instance World generation Dimension Dimension type World preset Biomes Carver Configured feature Tree Placed feature Environment attribute Noise settings Noise router Density function Noises Surface rule Structures Structure set Template pool Processor list Structure templates Removed Configured surface builder Data packs Caves & Cliffs Prototype Data Pack Phantom Frames Tutorials Importing Creating Optimizing Command blocks and functions Repairing a world corrupted by a data pack Content Custom enchantments Custom paintings Custom trims World generation New dimension Custom structures
Resource pack Components pack.mcmeta Pack format Language Models Blockstates Items Sounds (sounds.json) Shaders Textures Atlases Aa Fonts Colormaps Texts Waypoint styles regional_compliancies.json Equipment Debug Missing font character Missing model Missing texture Tools Slicer Legacy Texture Ender Unstitcher Tutorials Creating Loading Models Sound directory