tolpo

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/signerless/tolpo/main/assets/logo-dark.svg">
    <img alt="tolpo" src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/logo-light.svg" width="280">
  </picture>
</p>

<p align="center"><strong>Local-first control of TP-Link Tapo smart-home devices for AI agents.</strong></p>

<p align="center">

[![CI](https://github.com/signerless/tolpo/actions/workflows/ci.yml/badge.svg)](https://github.com/signerless/tolpo/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/signerless/tolpo/blob/main/LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

</p>

`tolpo` turns the Tapo devices on your network into a single interface that an AI agent, or
your own code, can read and control. It talks to each device directly over the LAN through the open
source [python-kasa](https://github.com/python-kasa/python-kasa) library, so no request ever leaves
your home and no vendor cloud sits in the path. The only credential it needs is the Tapo account the
devices already belong to.

It ships two interfaces over the same core:

- An **MCP server** that assistants such as Claude use as tools (`turn off the office lights`,
  `is any door open?`).
- An **HTTP API** with an OpenAPI description at `/docs`, for scripts and dashboards.

## Features

- **One view of the whole house.** Lights, plugs, the H100/H200 hub and its sensors, cameras and the
  doorbell, each with live state and a clear list of what can be changed.
- **Safe by default.** Reads are broad; writes are limited to power, brightness and color unless you
  opt in. Cameras, pairing and hub alarms stay read-only. Wi-Fi names and Matter setup codes are
  never returned.
- **Built for real homes.** Discovery combines broadcast with a direct per-address sweep, remembers
  devices between runs, retries the ones that are slow to wake, and reports honestly when something
  cannot be reached instead of pretending it is fine.
- **Fast to answer.** State is cached briefly and device names resolve instantly, so an agent is not
  blocked on a slow hub.
- **Tested.** A full suite runs against simulated devices, so it needs no hardware.

## Supported devices

tolpo works with whatever [python-kasa](https://github.com/python-kasa/python-kasa) can talk to, so the list is
longer than the hardware we own. The table keeps two things apart: what we have run against real devices, and
what python-kasa documents as supported but we have not tried.

| | Device | Tested here | Documented by python-kasa, not tried here | What an agent gets |
|---|---|---|---|---|
| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/light.svg" width="36" alt="Light bulb"> | Color bulbs | L430C | L430P, L530B, L530E, L530EA, L535E | State, brightness, white temperature and color |
| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/plug.svg" width="36" alt="Smart plug"> | Smart plugs | P115 | P110, P110M | State, plus power, voltage and current readings |
| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/hub.svg" width="36" alt="Hub"> | Hubs | H200 | H100, and S200B and S200D buttons paired to a hub | The sensors paired to it show up as devices of their own. Its alarm and pairing stay blocked |
| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/contact.svg" width="36" alt="Door and window sensor"> | Door and window sensors | T110 |  | Open or closed, low-battery flag |
| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/climate.svg" width="36" alt="Temperature and humidity sensor"> | Temperature and humidity sensors | T310 | T315 (the one with a display) | Temperature, humidity, low-battery flag |
| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/motion.svg" width="36" alt="Motion sensor"> | Motion sensors |  | T100 | Motion, as python-kasa documents it. Not checked on real hardware |
| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/leak.svg" width="36" alt="Water leak sensor"> | Water leak sensors | T300 |  | Leak alert and battery level |
| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/camera.svg" width="36" alt="Camera"> | Cameras | C225, C610, C465 | C100, C101, C110, C200, C210, C220, C325WB, C460, C520WS, C720, TC40, TC65, TC70 | State, battery where there is one, last alert and detection switches. Read-only, no video |
| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/doorbell.svg" width="36" alt="Video doorbell"> | Doorbells | D230 | D100C, D130 | State and battery. Read-only |

The C610 and the C465 are not on python-kasa's list yet, but both connected fine. The C465 needs the small
certificate fix in `compat.py`. The full upstream list is in
[python-kasa's SUPPORTED.md](https://github.com/python-kasa/python-kasa/blob/master/SUPPORTED.md).

A model that is not listed may still work, because tolpo hands the device to python-kasa and shows whatever it
reports. Run `tolpo scan` to find out. If a device works or does not, tell us through a
[device support issue](https://github.com/signerless/tolpo/issues/new?template=device_support.yml) so the table can improve.

## Requirements

- Python 3.11 or newer
- One or more TP-Link Tapo devices on the same network, already set up in the Tapo app
- Your Tapo account email and password
- [uv](https://docs.astral.sh/uv/) (or plain `pip`) to install

## Installation

### With npx

You need [Node](https://nodejs.org) and [uv](https://docs.astral.sh/uv/). Nothing is installed globally:

```bash
npx -y tolpo scan      # find your devices
npx -y tolpo mcp       # run as an MCP server
```

tolpo is a Python program. The npm package carries the Python code and runs it with uv, so the first run
downloads about forty Python packages and takes longer than later runs. If an AI client gives up waiting, run
`npx -y tolpo --help` once and start the client again.

### With Docker

For a machine that stays on, such as a Raspberry Pi or a Linux home server. The image is public, so pulling it
needs no login, and it is built for amd64 and arm64.

Keep the credentials in a file that only you can read, and pass it with `--env-file`:

```bash
(umask 077; printf 'TAPO_EMAIL=you@example.com\nTAPO_PASSWORD=your-password\n' > ~/.tolpo.env)

docker run --rm -i --network host --env-file ~/.tolpo.env ghcr.io/signerless/tolpo
```

That runs the MCP server over stdio. For the HTTP API, add a token, because it is no longer bound to loopback:

```bash
echo "TOLPO_TOKEN=$(openssl rand -hex 24)" >> ~/.tolpo.env

docker run -d --name tolpo --restart unless-stopped --network host --env-file ~/.tolpo.env \
  ghcr.io/signerless/tolpo serve --host 0.0.0.0
```

`--network host` lets the container find devices by UDP broadcast, and it only works on Linux. Docker Desktop on
macOS and Windows runs containers in a virtual machine that cannot see your devices that way, so use the npx
install there.

CI builds the image for both architectures and checks the MCP handshake inside it. Finding real devices from
inside a container has not been tried yet.

### From source

```bash
git clone https://github.com/signerless/tolpo && cd tolpo
uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python -e ".[dev]"
```

## Configuration

Credentials can come from environment variables or a config file. The server reads the file first,
then lets the environment override it.

```bash
export TAPO_EMAIL='you@example.com'
export TAPO_PASSWORD='your-password'
```

Or `~/.config/tolpo/config.toml` (run `chmod 600` on it, since it holds a password):

```toml
[tapo]
email = "you@example.com"
password = "your-password"
# or point at an existing JSON file instead of copying the secret:
# credentials_file = "~/.tapo_config.json"

[server]
host = "127.0.0.1"          # loopback only; a token is required to bind elsewhere
port = 8765
# token = "a-long-random-string"
# cache_ttl_seconds = 10

[discovery]
# subnets = ["192.168.1.0/24"]   # default: the /24 of your default-route interface
# hosts   = ["192.168.10.20"]    # devices that ignore broadcast or live on another VLAN
# sweep   = true                 # also probe every address in the subnet (networks up to /22)
interval_seconds = 600

[policy]
# Features an agent may write beyond power, brightness and color.
# Plain ids ("pan_left") or kind-qualified ones ("camera.state").
allow_write = []
```

Verify your setup with a read-only scan: `npx -y tolpo scan`, or `.venv/bin/tolpo scan` from a source checkout.

## Usage with Claude (MCP)

Put your credentials in `~/.config/tolpo/config.toml` (see Configuration, and `chmod 600` it). The server
reads that file by itself, so nothing secret ends up in your AI client's settings. Then register the server
once:

```bash
claude mcp add tolpo -- npx -y tolpo mcp
```

From a source checkout, point at your own copy instead:

```bash
claude mcp add tolpo -- $PWD/.venv/bin/tolpo mcp
```

If you would rather keep the credentials out of a file, pass them with `-e TAPO_EMAIL=... -e TAPO_PASSWORD=...`,
but your client will then store them in its own settings in plain text.

After the next restart you can ask things like "dim office-1 to 30%", "is any door open?" or "what is the
temperature upstairs?".

| Tool | What it does |
|---|---|
| `home_overview` | The whole house at a glance: what is on, open doors and windows, water alerts, offline devices, low batteries, temperatures |
| `list_devices` | Devices with state; filter by `kind` or name |
| `get_device` | Every feature of one device, and which ones are writable |
| `set_power` | Switch lights and plugs; accepts several targets and globs like `office*` |
| `set