openclaw-meshtastic

📡 OpenClaw plugin for Meshtastic LoRa mesh radios via meshx.

Connects your OpenClaw agent to the mesh — send messages, manage channels, scan for radios, ping peers, subscribe to live events. meshx ships a native MCP server with 26 auto-generated tools; this plugin tells OpenClaw how to spawn it.

⚠️ Requires meshx

This plugin does not talk to a radio directly — it connects to the meshx daemon via its MCP server.

# install meshx
curl -fsSL https://github.com/retr0h/meshx/raw/main/install.sh | sh

# start the daemon — the agent handles radio lifecycle
# (scan, pair, attach) via MCP tools
meshx server start

No --radio flag needed at startup. The agent discovers and attaches radios at runtime through scan_ble, scan_usb, pair_ble, and the rest of the BLE/USB tool surface.

🏗️ Architecture

flowchart TB
    R["📡 Radio\n(USB / TCP / BLE)"]
    D["meshx daemon\nmeshx server start"]
    M["meshx MCP server\nmeshx mcp start\n(26 tools + events)"]
    P["openclaw-meshtastic\n(MCP connector)"]
    A["OpenClaw agent"]

    R --> D
    D -- HTTP + SSE --> M
    M -- "JSON-RPC / stdio" --> P
    P --> A

Loading

🔧 Tools (26)

Auto-generated from the daemon's OpenAPI spec. When meshx adds an HTTP endpoint and runs just generate, the matching MCP tool appears.

Category	Tools
Discovery	health, list_radios, get_radio
Mesh state	list_channels, list_nodes, list_messages
Messaging	send_message (broadcast + DM via to_num)
Channels	mint_channel, import_channels, delete_channel, share_channel
Config	update_config, reboot_radio
Radio ops	ping_peer, traceroute_peer, sync_radio
BLE / USB	scan_ble, scan_usb, auto_detect_usb, pair_ble, list_ble_devices, forget_ble_device, set_ble_favorite, clear_ble_favorite
Events	subscribe_events, unsubscribe_events

Event subscriptions push live radio events (messages, ack/fail, peer sightings) as MCP Log notifications — no polling. Per-radio or unified (all radios). Resumable via since cursor.

📦 Install

Option 1 — register the MCP server directly

No plugin install needed:

openclaw mcp set meshx '{"command":"meshx","args":["mcp","start"]}'

Tools appear as meshx__send_message, meshx__list_radios, etc.

Option 2 — ClawHub bundle

openclaw plugins install clawhub:openclaw-meshtastic
openclaw gateway restart

The bundle ships .mcp.json — embedded Pi spawns meshx mcp start when the bundle is enabled.

Option 3 — from source

git clone https://github.com/retr0h/openclaw-meshtastic.git
openclaw plugins install ./openclaw-meshtastic
openclaw gateway restart

⚙️ Configure

MCP server (Option 1)

Pass daemon URL + auth via env:

openclaw mcp set meshx '{
  "command": "meshx",
  "args": ["mcp", "start"],
  "env": {
    "MESHX_MCP_SERVER": "http://192.168.1.10:4404",
    "MESHX_MCP_AUTH_TOKEN_FILE": "/path/to/token"
  }
}'

Defaults: http://127.0.0.1:4404, no auth (loopback).

Plugin bundle (Option 2 / 3)

No additional config needed — the .mcp.json in the bundle root tells OpenClaw how to spawn the MCP server. Override the daemon URL or auth token via env in the bundle settings if the daemon isn't on localhost.

📚 Docs

• meshx docs — daemon setup, keybindings, architecture
• meshx configuration — every flag / env / default
• MCP pivot design — original architecture notes

📄 License

MIT — see LICENSE.