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

The following must already be in place before following this guide.

System flow

Pressing a dashboard button triggers a chain: Home Assistant script, then the OliveTin API, then SSH to the Ubuntu server, then the bash script, then an RCON command to the Minecraft server.

Enable RCON on the Minecraft container

RCON is a remote console protocol built into Minecraft that allows commands to be sent to the server programmatically. It must be enabled and bound to localhost only for security.
Binding RCON to 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

The RCON password is stored in a .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'
Always use single quotes. They stop bash from interpreting characters like $, !, 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

A single bash script on the Ubuntu server handles all item-giving commands. It accepts the item name, amount, and player name as arguments, sanitizes the input, and sends the command to the Minecraft server via RCON.

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"
The 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

OliveTin is configured with a single action that accepts item, amount, and player as arguments. It connects to the Ubuntu Server via SSH and runs the bash script with those arguments. Input is validated using the 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

A REST command in Home Assistant is used to call the OliveTin API, passing the item, amount, and player as dynamic arguments in the payload.

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 }}" }
        ]
      }
Replace YOUR_OLIVETIN_IP with your OliveTin host's address. The Jinja2 variables are filled in at runtime by whatever calls the command.
If 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

A single reusable Home Assistant script with fields for item, amount, and player is used to call the REST command. This means only one script is needed regardless of how many different items or dashboard buttons you have.

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

The dashboard uses Mushroom Template Cards with custom Minecraft item images as buttons. Each button calls the single mc_give_item script with different item and amount values. Items are grouped into sections, each as a separate card on the dashboard.
Item images come from the Minecraft Wiki and live in /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
File names with spaces must be URL encoded in the dashboard config: 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;
    }
That's the full setup. Tapping a dashboard button runs the Home Assistant script, which calls OliveTin, which SSHs into the server, which runs the bash script, which sends the RCON command to Minecraft, all within a few seconds.