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.

	Device	Tested here	Documented by python-kasa, not tried here	What an agent gets
	Color bulbs	L430C	L430P, L530B, L530E, L530EA, L535E	State, brightness, white temperature and color
	Smart plugs	P115	P110, P110M	State, plus power, voltage and current readings
	Hubs	H200	H100, and S200B and S200D buttons paired to a hub	The sensors paired to it show up as devices of their own, and its event log is readable. With a higher level: siren, sensor settings, pairing
	Door and window sensors	T110		Open or closed, low-battery flag
	Temperature and humidity sensors	T310	T315 (the one with a display)	Temperature, humidity, low-battery flag
	Motion sensors		T100	Motion, as python-kasa documents it. Not checked on real hardware
	Water leak sensors	T300		Leak alert and battery level
	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. With a higher level: detection tuning, image and audio settings, pan and tilt, the memory card. Pictures and clips, for the cameras you enable
	Doorbells	D230	D100C, D130	State and battery, pictures and live video through the hub. With a higher level: ring sounds, quick replies, anti-theft, wake-up
	Robot vacuums		Models python-kasa has a cleaning module for	Status, start and stop, rooms and zones, suction and water, schedules. Built from the app's protocol and not tried on real hardware
	Door locks		Not supported by python-kasa	Not usable yet. The DL100, DL105, DL110, DL130 and DLW10 speak a protocol python-kasa does not know. tolpo can parse their discovery record, and nothing is connected to it yet

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"