Minecraft Server

Minecraft is a sandbox video game developed by Mojang Studios. Minecraft servers allow players to play the game online or via a local area network with other players. The Minecraft Server integration lets you retrieve information from a Minecraft server within Home Assistant. Both Java Edition and Bedrock Edition servers are supported.

Use cases

• Monitor whether a Minecraft server is online and responding.
• Track player counts and server capacity.
• Check which version a server is running.
• Trigger automations when a server goes offline or when a player joins or leaves.

Prerequisites

• Minecraft Java Edition servers must be beta version 1.8+ or release version 1.0+.
• Minecraft Java Edition servers with release version 1.16+ must set the configuration parameter enable-status to true in the server configuration file (server.properties).

Configuration

To add the Minecraft Server service to your Home Assistant instance, use this My button:

During setup you will be prompted to enter the address of the server.

Server address

The server address is a combination of the hostname and the port, where the port is optional. For SRV records, the port is automatically extracted. For all other cases the default port (25565 for Java Edition and 19132 for Bedrock Edition) is used, if the port is omitted. Here are some server address examples:

• SRV record: hypixel.net
• Hostname: mc.hypixel.net:25565 or mc.hypixel.net
• IP address: 192.168.0.123:19132 or 192.168.0.123

Supported functionality

This integration provides the following entities.

Binary sensors

• Connection status

Sensors

• Latency
• Version
• Protocol version
• Number of online players
  • Includes the player names list in the state attributes, if available. See Known limitations.
• Number of maximum players
• World Message / Message of the Day (MOTD)

For Bedrock Edition servers, the following sensors are also provided:

• Edition
  • Minecraft Pocket Edition (MCPE) or Minecraft Education Edition (MCEE)
• Game mode
• Map name

Automation examples

The easiest way to create automations is to import a ready-made blueprint and adjust it in the UI. The following examples cover common alerts and status updates for your Minecraft server.

If you want to build a custom automation instead:

1. Go to Settings > Automations & scenes.
2. Select Create automation.
3. Choose a trigger such as State or Numeric state.
4. Choose the relevant Minecraft server entity.
5. Add any conditions and the actions you want to run.

You can also start from a blueprint and customize it after importing it.

Offline alert

Performs an action when your Minecraft server stays offline for a chosen duration. Includes an editable default action that can be customized or deleted in the UI.

Prefer to configure this automation manually? Use the YAML below.

alias: Minecraft Server Offline Alert
triggers:
  - trigger: state
    entity_id: YOUR_SERVER_CONNECTION_SENSOR
    to: "off"
    for: minutes: 3

actions: - action: persistent_notification.create
  data:
    title: Minecraft Server Offline Alert
    message: The server is no longer responding.
    notification_id: minecraft_server_offline_alert_{{ trigger.entity_id }}

Latency alert

Performs an action when the Minecraft server latency exceeds a chosen threshold for a selected duration. Includes an editable default action that can be customized or deleted in the UI.

Prefer to configure this automation manually? Use the YAML below.

alias: Minecraft Server Latency Alert
triggers:
  - trigger: numeric_state
    entity_id: YOUR_LATENCY_SENSOR
    above: 200
    for: minutes: 3

actions: - action: persistent_notification.create
  data:
    title: Minecraft Server Latency Alert
    message: The server latency is too high.
    notification_id: minecraft_server_latency_alert_{{ trigger.entity_id }}

Player count changed

Performs an action when the number of players online changes on your Minecraft server. Includes an editable default action that can be customized or deleted in the UI.

Prefer to configure this automation manually? Use the YAML below.

alias: Minecraft Server Player Count Changed
triggers:
  - trigger: state
    entity_id: YOUR_PLAYERS_SENSOR

conditions:
  - condition: template
    value_template: >
      {{ trigger.from_state is not none and
         trigger.to_state is not none and
         is_number(trigger.from_state.state) and
         is_number(trigger.to_state.state) and
         trigger.from_state.state != trigger.to_state.state }}

actions: - action: persistent_notification.create
  data:
    title: Minecraft Server Player Count Changed
    message: |
      Players: {{ trigger.to_state.state }}
      Players list: {{ state_attr(trigger.entity_id, 'players_list') | join(', ') if state_attr(trigger.entity_id, 'players_list') else 'n/a' }}
    notification_id: minecraft_server_player_count_changed_{{ trigger.entity_id }}

Data updates

This integration pollsData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] the configured Minecraft servers every 60 seconds to refresh their status information. If the servers cannot be reached, the relevant entities become unavailable and the connection status sensor goes off.

Known limitations

• Player names are only available on Java Edition servers with release version 1.7.2+.

• Depending on the server, the player names list may not be shown completely. Some servers and plugins limit or completely hide this list or even replace the player names with fake ones to show some custom messages there.

• Bedrock Edition servers do not support SRV record lookups.

Troubleshooting

The server is unreachable

Symptom: “Failed to connect to server” or the connection sensor stays off

When you set up the integration, the connection check fails or the connection sensor remains off.

Description

This usually means the Minecraft server is not responding to status requests at all or not as expected.

Resolution

1. Verify the configured hostname or IP address and port are correct.
2. If you use a hostname or SRV record, confirm that DNS resolves correctly.
3. Check firewall and port-forwarding rules if the server is on another network.
4. For Java Edition servers with release version 1.16+, confirm that the configuration parameter enable-status is set to true in the server configuration file (server.properties).

Removing the integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. Next to the entry you want to remove, select the three dots menu. Then, select Delete.
   • Depending on the integration, the entries are listed under one of the following headings:
     • Devices
     • Hubs
     • Services
     • Integration entries
3. To confirm, select Delete.
   • Home Assistant also deletes the devices and entities of the entry.
4. If Home Assistant asks you to restart, restart Home Assistant.
5. If Home Assistant asks whether to also delete the application credentials, select Remove or Keep.
   • If you keep them, Home Assistant uses them automatically when you add the integration again.
   • To delete them later, refer to Deleting application credentials.