tolpo

Local-first control of TP-Link Tapo smart-home devices for AI agents.

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

The aim is that everything the Tapo app can do on your network can also be done by the agent: lights, plugs, hubs and their sensors, cameras, doorbells, robot vacuums, schedules, firmware, rooms, pairing, and even what the devices say to the internet. That is a lot of power, so every action has a level, and only the first levels are on until you raise them. See What an agent can do and the Security model.

Features

• Lights, plugs, the H100/H200 hub and its sensors, cameras and the doorbell, each with live state and a list of what can be changed.
• The parts of the Tapo app are split into areas, such as lights, plugs, cameras, doorbells and the network. tolpo remembers which kinds of device it found in earlier runs, and an area for a kind you have never had stays off.
• Every action has a level from 0 to 4. Reading and reversible control (power, brightness, color) are on. Settings, security changes and things that are hard to undo, such as pairing or a factory reset, stay off until you raise the level, and the last two kinds also need a confirmation phrase on every call. Wi-Fi names, setup codes, passwords and tokens are never returned.
• A camera you name in the config gives an agent a still picture, a short run of pictures or a saved clip, through the same video channel the Tapo app uses. No extra camera account is needed.
• Discovery combines a broadcast with a direct per-address sweep, remembers devices between runs and retries the ones that are slow to wake. When a device cannot be reached, the answer says which one and why.
• State is cached briefly and device names resolve at once, so an agent is not blocked on a slow hub.
• A full test suite runs against simulated devices, so it needs no hardware.

Supported devices

tolpo works with whatever 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.

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.

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 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
• ffmpeg, only if you want pictures from cameras
• uv (or plain pip) to install

Installation

With npx

You need Node and uv. Nothing is installed globally:

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:

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

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. The image has no ffmpeg, so camera pictures do not work in it yet.

From source

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.

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

[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

areas = ["lights", "plugs", "hub"] # which parts offer tools; empty means every part for the devices you own

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

The highest level of action an agent may use, from 0 to 4. See the Security model.

tier = 1

Single device methods an agent may use above tier, for example ["setLedStatus"].

allow_methods = []

Features an agent may write beyond power, brightness and color.

Plain ids ("pan_left") or kind-qualified ones ("camera.state").

allow_write = []

[cameras]

Pictures are off for every camera until you name it here, as it is called in the Tapo app.

snapshots = [] # for example ["Hallway Cam"]

Optional. A camera account made in the Tapo app switches pictures to the standard RTSP stream.

username = "camera-account-name"

password = "camera-account-password"

ffmpeg = "/opt/homebrew/bin/ffmpeg" # only if ffmpeg is not on your PATH

clip_dir = "/Users/you/tolpo-clips" # the one folder where camera clips may be saved; no folder, no clips

Environment variables override the file: TOLPO_CONFIG (the file itself), TOLPO_CREDENTIALS_FILE, TOLPO_TIER, TOLPO_AREAS (names separated by commas), TOLPO_SNAPSHOTS, TOLPO_CLIP_DIR, TOLPO_FFMPEG, TOLPO_CAMERA_USERNAME and TOLPO_CAMERA_PASSWORD. A tier that is not a whole number from 0 to 4 stops the server from starting.

Some parts keep their own files, so that no secret ends up in the main one. Automation keeps its rules and alert outbox, and the local rooms and groups are kept in ~/.local/state/tolpo (change it with TOLPO_STATE_DIR). The network area reads ~/.config/tolpo/network.toml (change it with TOLPO_NETWORK_CONFIG)