ThingWire

Give AI agents hands. Control real hardware through natural language.

Why ThingWire

AI agents are great at reasoning. They're terrible at interacting with the physical world. ThingWire bridges that gap. Your ESP32 publishes a W3C WoT Thing Description over MQTT, the gateway reads it, and auto-generates MCP tools. Now Claude can read your temperature sensor and flip your relay, with a real safety layer between "AI said so" and "the relay clicked."

No custom integrations. No hand-written tool definitions. Plug in a new device, and the AI agent discovers it automatically.

How It Works

┌─────────────────────┐
│  Claude / Cursor /   │
│  Any MCP Client      │
└─────────┬───────────┘
          │ MCP tools (read_temperature, set_relay, ...)
          ▼
┌─────────────────────┐
│  ThingWire Gateway   │  Python, FastMCP, paho-mqtt
│  ┌────────────────┐  │
│  │  Safety Layer   │  │  allowlists, rate limits, audit log
│  └────────────────┘  │
└─────────┬───────────┘
          │ MQTT
          ▼
┌─────────────────────┐
│  ESP32-S3 Device     │  WoT Thing Description + sensors + actuators
│  DHT22 / PIR / Relay │
└─────────────────────┘

1. ESP32 boots and publishes its capabilities as a WoT Thing Description to MQTT
2. Gateway subscribes, parses the TD, and compiles it into typed MCP tools
3. AI agent calls tools like read_temperature or set_relay
4. Safety layer checks permissions, rate limits, and flags dangerous actions
5. Command goes to the device over MQTT. Response comes back the same way.

Quickstart

You don't need hardware. The virtual device simulator gets you running in under 5 minutes.

Option A: pip install

pip install thingwire

# Initialize project files
thingwire init

# Start MQTT broker
docker compose up -d

# Start virtual device (simulates ESP32 with sensors + relay)
python -m thingwire.virtual_device  # OR: python scripts/virtual_device.py

# Start gateway (new terminal)
thingwire serve

Option B: From source

git clone https://github.com/thingwire-dev/thingwire
cd thingwire
pip install -e ".[dev]"
thingwire serve

Connect your MCP client

Add this to your claude_desktop_config.json (or equivalent for Cursor):

{
  "mcpServers": {
    "thingwire": {
      "command": "thingwire",
      "args": ["serve"],
      "env": {
        "THINGWIRE_MQTT_BROKER": "localhost"
      }
    }
  }
}

Done. Open Claude Desktop and start talking to your hardware.

What You Can Ask Claude

Once connected, try these:

• "What devices are online right now?"
• "What's the temperature and humidity?"
• "Turn on the relay."
• "Is there motion in the room?"
• "Turn on the relay when temperature goes above 30C."
• "Show me the last 10 commands in the audit log."
• "What actions are allowed on this device?"

The AI agent sees real MCP tools generated from the device's own Thing Description. It knows what the device can do, what units the sensors report in, and what safety constraints exist.

Architecture

thingwire/
├── src/thingwire/            Python gateway (pip install thingwire)
│   ├── cli.py                    CLI: thingwire serve / init / devices
│   ├── td_loader.py              Parse WoT Thing Descriptions
│   ├── tool_compiler.py          WoT TD → MCP tools (core differentiator)
│   ├── mcp_server.py             MCP server wiring
│   ├── mqtt_bridge.py            MQTT device discovery + commands
│   ├── safety.py                 Permissions, rate limits, deadman switch
│   └── audit_log.py              SQLite audit trail
├── firmware/                 ESP32-S3 firmware (PlatformIO/Arduino)
│   └── src/
│       ├── main.cpp, wifi_manager.cpp, mqtt_client.cpp
│       ├── sensor_registry.cpp, actuator_controller.cpp
│       └── wot_td_generator.cpp
├── td-library/               Pre-built Thing Descriptions for common hardware
├── scripts/
│   └── virtual_device.py    Device simulator (no hardware needed)
└── examples/                 Demo scenarios

Safety

This is not a toy. AI agents controlling physical hardware need guardrails. Every actuator command passes through the safety layer before reaching any device.

• Per-device allowlists configure exactly which actions each device permits
• Rate limiting with sliding windows prevents runaway commands
• Dangerous action confirmation for actions marked safe: false in the WoT TD
• Deadman switch disables actuators if the device heartbeat stops
• SQLite audit log records every command with timestamp, parameters, and result

The safety config lives in safety_config.yaml. You define what's allowed. The AI agent can only operate within those boundaries.

Hardware

For real hardware (MVP):

Component	Purpose
ESP32-S3-DevKitC-1	Microcontroller (any ESP32-S3 works)
DHT22	Temperature and humidity sensor
PIR sensor	Motion detection
5V relay module	Actuator output

No hardware? The virtual device simulator generates realistic sensor data and responds to actuator commands. Everything works the same from the AI agent's perspective.

python3.11 scripts/virtual_device.py --broker localhost

MQTT Topics

thingwire/{device_id}/td          # WoT Thing Description (retained)
thingwire/{device_id}/telemetry   # Sensor readings (every 5s)
thingwire/{device_id}/command     # Actuator commands
thingwire/{device_id}/status      # Online/offline (LWT)

Configuration

All settings via environment variables, prefixed with THINGWIRE_:

Variable	Default	Description
THINGWIRE_MQTT_BROKER	localhost	MQTT broker hostname
THINGWIRE_MQTT_PORT	1883	MQTT broker port
THINGWIRE_DEVICE_TOPIC_PREFIX	thingwire	MQTT topic prefix for device discovery
THINGWIRE_AUDIT_DB_PATH	data/audit.db	Path to SQLite audit log
THINGWIRE_SAFETY_CONFIG_PATH	safety_config.yaml	Path to safety rules
THINGWIRE_LOG_LEVEL	INFO	Log level (DEBUG, INFO, WARNING, ERROR)

Development

cd gateway

# Install dependencies
python3.11 -m pip install -r requirements.txt
python3.11 -m pip install -e ".[dev]"

# Run tests
python3.11 -m pytest tests/ -v

# Lint
python3.11 -m ruff check gateway/

# Type check
python3.11 -m mypy gateway/ --strict

Roadmap

• Multi-device orchestration (coordinate actions across devices)
• Prometheus metrics export
• OTA firmware updates via MCP tools
• BLE device support alongside MQTT
• Home Assistant integration
• Pre-built TD templates for common sensors

Contributing

PRs welcome. If you're adding a new device type, include a WoT Thing Description and a virtual device simulator for it.

License

MIT

---

Suggested GitHub topics: iot mcp ai-agent esp32 home-automation wot claude mqtt hardware sensors