INSTAR AI Agent Interface

This Python repository uses paho-mqtt v2 to expose your cameras MQTT API giving a FastMCP server access to the entire control interface:

• Github Repository

Installation

Prerequisites

• Make sure you have Hermes Agent v0.21.0+ installed (this server should work with any Agent Harness that supports MCP - but only tested with Hermes)
• Make sure that your INSTAR cameras MQTT broker is active and reachable (or connect your camera to an external broker)
• Now you can installcamera-mcp locally by first cloning the repository and then running a pip install command:

git clone https://github.com/mpolinowski/instar-mqtt-mcp.git
cd instar-mqtt-mcp
pip install -e .
    Successfully built mqtt-runtime
    Installing collected packages: mqtt-runtime
    Attempting uninstall: mqtt-runtime
        Found existing installation: mqtt-runtime 0.1.0
        Uninstalling mqtt-runtime-0.1.0:
        Successfully uninstalled mqtt-runtime-0.1.0
    Successfully installed mqtt-runtime-0.1.0

You can verify that the installation was successful by checking

which camera-mcp
~/.local/bin/camera-mcp

Adding the MCP Server to Hermes

The server is not yet added to the official Hermes catalogue. Once the server is published you can run the following command and everything should just work:

hermes mcp install instar-camera

The catalog manifest handles git checkout, pinned ref, venv bootstrap, and prompts for MQTT credentials. This is the supported production path.

Local development / testing

As long as the server is not yet published use hermes mcp add or when developing locally:

Hermes needs to know the details for your MQTT broker login and your camera's MQTT client configuration. Just add the following variables to your Hermes environment:

echo "INSTAR_MQTT_HOST=<your-broker-host>" >> ~/.hermes/.env
echo "INSTAR_MQTT_PORT=<your-broker-port>" >> ~/.hermes/.env
echo "INSTAR_MQTT_USERNAME=<your-mqtt-user>" >> ~/.hermes/.env
echo "INSTAR_MQTT_PASSWORD=<your-mqtt-password>" >> ~/.hermes/.env
echo "INSTAR_MQTT_CLIENT_PREFIX=<your-topic-prefix>" >> ~/.hermes/.env
echo "INSTAR_MQTT_CAMERA_ID=<your-camera-id>" >> ~/.hermes/.env
source ~/.hermes/.env

NOTE: That these env variables will be available to your Hermes Agent. If you try to run test_application.py manually the code will fall back to .env in the repository root - make sure you added your MQTT credentials there as well. I added a dummy file - just edit it with your credentials.

Now we can add the local version of the MCP server by running:

❯ hermes mcp add instar_camera \
  --command "$(which camera-mcp)"

  Connecting to 'instar_camera'...
  ✓ Connected! Found 6 tool(s) from 'instar_camera':
    set_camera_value                Set a camera capability value and wait for camera observatio...
    get_camera_state                Get current observed state of a camera capability.
Returns ...
    wait_camera_state               Wait for camera capability to reach expected value.
Blocks ...
    get_camera_health               Check operational health and connectivity of camera integrat...
    get_camera_image                Retrieve the most recently received image from camera.
This...
    list_camera_capabilities        List all capabilities/settings the camera runtime can operat...
  Enable all 6 tools? [Y/n/select]: y
  ✓ Saved 'instar_camera' to ~/.hermes/config.yaml (6/6 tools enabled)
  Start a new session to use these tools.

Hermes will probe the server, list the six tools, and prompt to enable them. After saving, verify:

hermes mcp list
hermes mcp test instar_camera

 MCP Servers:

 Name             Transport                      Tools        Status
 ──────────────── ────────────────────────────── ──────────── ──────────
 instar_camera    ~/.local/bin/...   all          ✓ enabled

 Testing 'instar_camera'...
 Transport: stdio → ~/.local/bin/camera-mcp
 Auth: none
 ✓ Connected (1360ms)
 ✓ Tools discovered: 6
   set_camera_value            Set a camera capability value and wait for camera obser...
   get_camera_state            Get current observed state of a camera capability.
Returns...
   wait_camera_state           Wait for camera capability to reach expected value.
Blocks...
   get_camera_health           Check operational health and connectivity of camera int...
   get_camera_image            Retrieve the most recently received image from camera.
This...
   list_camera_capabilities    List all capabilities/settings the camera runtime can o...

Skill Integration

A Hermes skill instar-camera ships with the repo at ./skills/instar-camera/SKILL.md. The skill is independent of MCP installation and teaches the agent when and how to use the camera tools. Just copy the skill into the Hermes config directory:

mkdir -p ~/.hermes/skills/home-automation/instar-camera
cp ~/instar-mqtt-mcp/skills/instar-camera/SKILL.md ~/.hermes/skills/home-automation/instar-camera/

Hermes will discover it as a local skill and guide the agent to select the correct MCP tools after you restarted the service.

How does it work?

As already said in the beginning, this Python repository uses paho-mqtt v2 to expose your cameras MQTT API giving a FastMCP server access to the entire control interface. Check the MQTT documentation for the available MQTT topics:

I would recommend a tool like the MQTT Explorer to investigate how everything works. But you don't have to aanymore! This is now your agents job :)

Invoking the INSTAR Skill

Just ask your agents about a specific topic you want to toggle. In the example I want Hermes Agent to find out if the Alarm Areas "yellow" (alarm/areas/yellow/enable) and red (alarm/areas/red/enable) are enable - and if not, do so:

Lean back and have a cup of coffee while your agents studies the MCP server - it should come back after a short while and tell you that the areas are toggled! But now the important part - your agent will forget what it did just now and has to re-investigate everything again when you ask the same question later... so make it a skill:

This will create another skill file that is a step-by-step guide to get it done in no time.