Thingwire

ThingWire

WoT Thing Description → MCP tools. Point AI agents at real hardware.

[](LICENSE) [](https://python.org) [](https://www.espressif.com/) [](https://mqtt.org/) [](https://www.w3.org/TR/wot-thing-description11/) [](https://modelcontextprotocol.io/)

What it does

Your ESP32 publishes a W3C WoT Thing Description over MQTT. ThingWire reads it and auto-generates MCP tools. Claude (or any MCP client) can then call read_temperature, set_relay, etc. with no hand-written tool definitions.

A safety layer sits between the AI and the hardware: per-device action allowlists, rate limits, dangerous-action confirmation, and a full audit log.

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 and rate limits before passing the command on
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 without any physical devices.

From source

git clone https://github.com/thingwire-dev/thingwire
cd thingwire

# Install
pip install -e ".[dev]"

# Start MQTT broker
docker compose up -d

# Start virtual device (simulates ESP32 with sensors + relay)
python scripts/virtual_device.py --broker localhost

# Start gateway (new terminal)
thingwire serve

PyPI (coming soon)

pip install thingwire
thingwire serve

Connect your MCP client

Add to claude_desktop_config.json:

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

Example queries

Once connected, you can ask things like:

• "What devices are online right now?"
• "What's the temperature and humidity?"
• "Turn on the relay."
• "Is there motion in the room?"
• "Show me the last 10 commands in the audit log."

The agent sees MCP tools generated from the device's own Thing Description, including units and safety constraints.

Repository layout

thingwire/
├── src/thingwire/            Python gateway
│   ├── cli.py                    CLI entry point
│   ├── td_loader.py              Parse WoT Thing Descriptions
│   ├── tool_compiler.py          WoT TD → MCP tools
│   ├── 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

Every actuator command passes through the safety layer before reaching any device.

• Per-device allowlists define 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. The AI agent can only operate within the boundaries you define there.

Hardware

Tested with:

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

Any ESP32-S3 board works. Flash the firmware with PlatformIO, configure firmware/src/config.h, and it will start publishing its Thing Description on boot.

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 |

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/

# Type check
mypy src/thingwire/ --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](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: thingwire-dev
• Source: thingwire-dev/thingwire
• License: MIT

Install and usage instructions live in the source repository linked above.