Minecraft Commands from Home Assistant
Send Minecraft server commands, like giving items to players, from a Home Assistant dashboard using OliveTin and a bash script. Mushroom Cards act as buttons with custom Minecraft item images.
Contents
- Prerequisites
- System flow
- Enable RCON on the Minecraft container
- Create the .env file
- Create the bash script
- Configure OliveTin
- Create the Home Assistant REST command
- Create the Home Assistant script
- Set up the dashboard
Prerequisites
- A Minecraft server running in Docker with the itzg/minecraft-server image.
- OliveTin running in Docker, on the same host or a separate one.
- SSH key access from OliveTin to the system hosting the Minecraft server.
- Home Assistant running and reachable on your network.
- Mushroom Cards and card-mod installed in Home Assistant through HACS.
- SSH access to your Ubuntu server.
System flow
Enable RCON on the Minecraft container
127.0.0.1 keeps it reachable only from the host itself, never from your LAN or the internet. RCON sends plaintext, has no encryption, and is vulnerable to brute-force attacks, so never expose it.Update your docker-compose.yaml:
Open /home/containers/minecraft-server/docker-compose.yaml and add:
services:
minecraft-server:
env_file:
- .env
environment:
ENABLE_RCON: "true"
RCON_PORT: 25575
RCON_PASSWORD: ${RCON_PASSWORD}
ports:
- "127.0.0.1:25575:25575"
Restart the container:
cd /home/containers/minecraft-server
docker compose down && docker compose up -d
Create the .env file
.env file in the same directory as the docker-compose.yaml. Docker Compose automatically reads this file, so the password only needs to be defined in one place. The file permissions are locked down so only the owner can read it.Create and secure the .env file:
nano /home/containers/minecraft-server/.env
Add the password in single quotes so special characters are safe:
RCON_PASSWORD='yourpassword'
$, !, and @. The one character you can't use inside them is a single quote.Lock down the permissions and verify:
chmod 600 /home/containers/minecraft-server/.env
ls -la /home/containers/minecraft-server/.env
Expected output:
-rw------- 1 youruser youruser 67 Apr 21 10:38 .env
-rw------- means only the owner can read or write the file. That's correct.Create the bash script
Create the script:
nano /home/youruser/scripts/mc-give.sh
#!/bin/bash
source /home/containers/minecraft-server/.env
ITEM=$(echo "$1" | tr -cd '[:alnum:]_') # Only allow alphanumeric and underscores
AMOUNT=$(echo "$2" | tr -cd '[:digit:]') # Only allow numbers
PLAYER=$(echo "$3" | tr -cd '[:alnum:]_') # Only allow alphanumeric and underscores
PLAYER=${PLAYER:-YOUR_PLAYER} # Default player if not provided
docker exec minecraft-server rcon-cli --password "$RCON_PASSWORD" "give $PLAYER minecraft:$ITEM $AMOUNT"
tr -cd commands remove any character that isn't alphanumeric or an underscore, so unexpected input never reaches the server.Make it executable:
chmod +x /home/youruser/scripts/mc-give.sh
Configure OliveTin
ascii_identifier type which restricts input to alphanumeric characters and underscores.Add the action to OliveTin's config.yaml:
Open your OliveTin config.yaml and add the following action:
actions:
- id: mc-give
title: Give Minecraft Items
shell: ssh user@YOUR_SERVER_IP '/home/youruser/scripts/mc-give.sh {{ item }} {{ amount }} {{ player }}'
arguments:
- name: item
title: Item
type: ascii_identifier
- name: amount
title: Amount
type: int
- name: player
title: Player
type: ascii_identifier
default: YOUR_PLAYER
maxConcurrent: 1
timeout: 120
icon: restart
popupOnStart: execution-dialog-stdout-only
maxConcurrent: 1 prevents duplicate commands from firing at once. ascii_identifier matches valid Minecraft item IDs and usernames.Restart OliveTin:
docker restart olivetin
Create the Home Assistant REST command
Add the REST command to Home Assistant:
Open your Home Assistant configuration.yaml (or rest_commands.yaml if defined in the configuration.yaml) and add the following:
rest_command:
mc_give_item:
url: "http://YOUR_OLIVETIN_IP:1337/api/StartAction"
method: POST
headers:
Content-Type: application/json
payload: >
{
"bindingId": "mc-give",
"arguments": [
{ "name": "item", "value": "{{ item }}" },
{ "name": "amount", "value": "{{ amount }}" },
{ "name": "player", "value": "{{ player }}" }
]
}
YOUR_OLIVETIN_IP with your OliveTin host's address. The Jinja2 variables are filled in at runtime by whatever calls the command.configuration.yaml contains rest_command: !include rest_commands.yaml, leave out the rest_command: line above.Reload the configuration or restart Home Assistant.
Create the Home Assistant script
Add the script to scripts.yaml:
scripts.yaml must be declared in configuration.yaml as script: !include scripts.yaml.mc_give_item:
alias: "MC - Give Item"
fields:
item:
description: "Minecraft item name"
example: "diamond_sword"
amount:
description: "Amount to give"
example: "10"
player:
description: "Player name"
default: "YOUR_PLAYER"
example: "YOUR_PLAYER"
sequence:
- action: rest_command.mc_give_item
data:
item: "{{ item }}"
amount: "{{ amount }}"
player: "{{ player | default('YOUR_PLAYER') }}"
Reload scripts in Home Assistant.
Set up the dashboard
mc_give_item script with different item and amount values. Items are grouped into sections, each as a separate card on the dashboard./config/www/minecraft/Icons/ on your Home Assistant host. Files in /config/www/ are served at /local/.Download the item images:
mkdir -p /config/www/minecraft/Icons/Tools
mkdir -p /config/www/minecraft/Icons/Armor
mkdir -p /config/www/minecraft/Icons/Bricks\ -\ Planks\ -\ Raw
mkdir -p /config/www/minecraft/Icons/Decor
mkdir -p /config/www/minecraft/Icons/Doors
mkdir -p /config/www/minecraft/Icons/Fence
mkdir -p /config/www/minecraft/Icons/Fire\ -\ Light
mkdir -p /config/www/minecraft/Icons/Food
mkdir -p /config/www/minecraft/Icons/Seeds
mkdir -p /config/www/minecraft/Icons/Range\ Weapons
mkdir -p /config/www/minecraft/Icons/Transport
Put each image in the matching subfolder, then confirm it loads in your browser:
http://YOUR_HA_IP:8123/local/minecraft/Icons/Tools/Netherite%20Sword.png
Netherite Sword.png becomes Netherite%20Sword.png.Add the dashboard cards:
Add each section as its own vertical-stack card. Use the picture field for local image paths; icon is only for mdi: icons. Separate cards let you reorder sections and add spacing cards between them.
type: vertical-stack
cards:
- type: markdown
content: "## 🗂️ Section Title"
- type: grid
columns: 2
square: false
cards:
- type: custom:mushroom-template-card
primary: Item Name
secondary: x1
picture: /local/minecraft/Icons/SubFolder/Item%20Name.png
tap_action:
action: perform-action
perform_action: script.mc_give_item
data:
item: item_id
amount: 1
For spacing between sections, add this markdown card:
type: markdown
content: " "
text_only: true
card_mod:
style: |
ha-card {
padding-top: 20px;
padding-bottom: 20px;
box-shadow: none;
background: none;
}