
Tapo MCP
io.github.mihai-dinculescu由 GitHub 账号 mihai-dinculescu 发布v0.7.0更新于 Nov 12, 2026
MCP server for discovering and controlling TP-Link Tapo smart home devices via AI Agents
概览
该 MCP 服务器可在局域网中发现 TP-Link Tapo 智能家居设备,让助手列出、控制并读取设备状态,包括摄像头快照。
- 可以做什么
- 列出发现的 Tapo 设备并读取设备当前状态
- 开关设备,设置亮度、颜色、色相/饱和度或色温
- 从 Tapo 摄像头拍摄 JPEG 静态快照,可选返回短期有效链接
- 读取能耗与功率数据(按小时、按天、按月、实时电表、每 5 分钟功率)
- 读取温湿度记录、摄像头侦测事件以及网关子传感器的触发日志
- 适用场景
- 当你希望助手操作家中的 Tapo 灯、插座、传感器和摄像头时适用:开关设备、调节灯光、查看传感器读数或用电情况,或按需抓取摄像头快照。
- 运行要求
- 以本地 HTTP 服务器运行(Docker 镜像,Streamable HTTP,端点 /mcp)。需要 Tapo 账号邮箱和密码(TAPO_MCP_USERNAME、TAPO_MCP_PASSWORD)以及发现目标 IP,通常是网络广播地址(TAPO_MCP_DISCOVERY_TARGET)。拍摄快照还需 TAPO_MCP_CAMERA_USERNAME 和 TAPO_MCP_CAMERA_PASSWORD。UDP 广播发现需要主机网络;容器绑定 0.0.0.0,必须设置 TAPO_MCP_API_KEY。
安装
在 SourceWeft 中
- 打开 控制台中的 Tapo MCP,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
tapo-mcp
MCP server that exposes Tapo smart-home devices as AI-callable tools and resources via the Model Context Protocol.
Built on the tapo crate and the rmcp SDK. Runs as an HTTP server (Streamable HTTP transport).
Example Prompts
"List all my Tapo devices"
"Turn off the office light"
"Turn on smart plug 4 on the power strip"
"Is the office light on?"
"Set the bedroom light to 50% brightness"
"Change the living room light to Coral"
"Take a snapshot from the baby monitor"
"What's the temperature in the kitchen?"
"Show me the last 24 hours of temperature from the living room temperature and humidity sensor"
"List the 5 most recent events on the smart button"
"How much energy did the washing machine plug use each day this month?"
"Show me the TV's power draw over the last 6 hours"
Tools
Resources
Capabilities
Devices and child devices expose separate lists of set and get capabilities they support. Child devices have no IP of their own; their ip is their parent's, which is the one to pass with the child's id.
Set Capabilities
Get Capabilities
Configuration
All configuration is via environment variables prefixed with TAPO_MCP_:
Clients connect to the MCP endpoint at /mcp on that address, for example http://127.0.0.1:3000/mcp. / still works but is deprecated: it logs a warning and will be removed in a later release.
Authentication
When TAPO_MCP_API_KEY is set, the server requires every HTTP request except /livez and snapshot links to include an Authorization: Bearer <key> header. Requests with a missing or invalid token receive a 401 Unauthorized response.
When the variable is unset (or empty/whitespace-only), the server runs without authentication.
Network exposure
The server enforces the MCP Streamable HTTP DNS-rebinding protection. By default only loopback Host headers (localhost, 127.0.0.1, ::1) are accepted, which prevents a malicious web page from reaching a locally running server via DNS rebinding. Requests to the MCP endpoint with any other Host receive a 403 Forbidden response, and the server logs a warning that names the refused host. Snapshot links are not covered by this check (see Snapshot links).
To reach the server over the LAN or from another host, set TAPO_MCP_ALLOWED_HOSTS to the exact hostname(s) or host:port authorities clients connect to, for example TAPO_MCP_ALLOWED_HOSTS="tapo-mcp.lan:3000,192.168.1.50:3000". This replaces the loopback default, so include loopback entries as well if you still need them.
To avoid shipping unauthenticated smart-home control, the server refuses to start when it binds to a non-loopback address (for example 0.0.0.0:3000) without TAPO_MCP_API_KEY set. Set an API key, or bind to a loopback address.
Snapshot links
Some MCP clients don't pass image results on to the model, and others show the image to the model but give it nothing it can hand to the user. When TAPO_MCP_PUBLIC_URL is set, take_snapshot also returns a url (and its expires_at) pointing at <TAPO_MCP_PUBLIC_URL>/snapshots/<token>.jpg, so the agent can share the link or download the file.
- The link is served without the API key, so a browser can open it directly. The
Hostallowlist fromTAPO_MCP_ALLOWED_HOSTSdoes not apply to it either. The random token in the path is the only credential: anyone holding the link can view that frame until it expires. - Each link is valid for 5 minutes. Snapshots are kept in memory only and never written to disk. Expired snapshots are cleared out within a minute, and at most the 1024 most recent are kept.
- Behind an authenticating reverse proxy (Cloudflare Access and similar), links opened in a browser that is already signed in to the proxy work. Non-browser fetches (
curl, an agent downloading the file) need the proxy's own credential or a policy exception for/snapshots/.
When TAPO_MCP_PUBLIC_URL is unset, no link is returned and the /snapshots/ route is not served.
OpenTelemetry
To export traces, set OTEL_EXPORTER_OTLP_ENDPOINT to the base URL of an OTLP/HTTP collector (e.g. http://alloy.monitoring:4318); the server sends them to /v1/traces under it. To send them to another path, set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT to the full URL instead. OTEL_RESOURCE_ATTRIBUTES adds resource attributes. RUST_LOG (default tapo_mcp=info) also decides which spans are exported.
What gets traced:
- Tool calls. Each
tools/callrequest gets one server span namedtools/call <tool>, covering the whole call, following the OpenTelemetry MCP semantic conventions. It carriesmcp.method.name,gen_ai.tool.name(only for tools the server provides),gen_ai.operation.name,jsonrpc.request.id,mcp.session.idandmcp.protocol.version, plustapo.device.idandtapo.device.ipwhere the tool takes them. A failed call has error status anderror.type(the JSON-RPC error code, ortool_error). Inside it, thecheck_devicespan covers the verification that the device ID matches at the given IP, andget_capability,set_capabilityorcapture_snapshotcovers the device request.get_capabilityandset_capabilitycarrytapo.capability, andcontrol_devicehas oneset_capabilityspan for each capability it applies, then aget_capabilityspan for the device info it reads back. A failed step has error status anderror.typeset to the kind of failure, such asDeviceNotFoundorWrongDeviceType. - Background jobs.
refresh_devicesfor each device discovery, andprune_snapshotsfor each sweep of expired snapshot links.
Credentials, the API key and image data are never recorded. Tool arguments are not recorded either, except id and ip, and a failed call's error message, which can repeat the value that was rejected.
Incoming W3C trace context is honoured. When the request's params._meta has a traceparent (and optionally tracestate), as MCP clients that trace their calls send, the tool call span becomes its child and joins that trace. A traceparent header on the HTTP request that carries the call, for example from a tracing reverse proxy, is then recorded as a span link. Without _meta context, the HTTP header is used as the parent instead. Without either, the span starts a new trace.
Deployment
Docker
Note: The image binds to
0.0.0.0:3000, soTAPO_MCP_API_KEYis required — the server refuses to start on a non-loopback address without it (see Network exposure). To reach the server by hostname or LAN IP rather than loopback, also setTAPO_MCP_ALLOWED_HOSTS. To get snapshot links, add-e TAPO_MCP_PUBLIC_URL="https://tapo.example.com".
Note:
--network hostis required so the container can reach Tapo devices on your local network via UDP broadcast for discovery. On macOS and Windows,--network hostis not supported — you can use-p 3000:3000instead, but device discovery won't work as Docker Desktop runs containers inside a VM without LAN access.
Kubernetes
Create the Secret and ConfigMap first:
Then apply the Deployment:
Note:
hostNetwork: trueis required for UDP broadcast discovery, similar to--network hostin Docker. Because clients reach the server by node IP or hostname rather than loopback, setTAPO_MCP_ALLOWED_HOSTSaccordingly (see Network exposure). To get snapshot links, addTAPO_MCP_PUBLIC_URLto the ConfigMap and the Deployment'senv.
Health checks
GET /livez answers 200 OK while the server is running. It needs neither the API key nor a Host from TAPO_MCP_ALLOWED_HOSTS, so a liveness probe works as it is.
The server uses about 15 MiB of memory. Snapshots for snapshot links are kept in memory for 5 minutes, which is what the 256 MiB limit above leaves room for.
OpenClaw
The tapo skill for OpenClaw makes it easy to use a deployed tapo MCP server from OpenClaw agents.
Install it with:
Contributing
Contributions are welcome and encouraged! See /tapo-mcp/CONTRIBUTING.md.
Footnotes
-
Set on each camera in the Tapo app under Camera Settings > Advanced Settings > Camera Account. Distinct from your TP-Link cloud account. ↩ ↩2
-
While a background discovery runs, tool calls that contact a device wait for it to finish, and the discovery waits for calls already in progress. A run takes about
TAPO_MCP_DISCOVERY_TIMEOUTseconds plus a few more to log in to the devices, and longer if a device is slow to respond. A short interval means these pauses happen often: at15with the default timeout, tool calls can be held up for several seconds out of every 15.list_devicesand thetapo://devicesresource never wait. ↩ ↩2
来源:tapo-mcp/README.md,提交 7cc850d
工具
0版本历史
8- v0.7.0最新Nov 12, 2026
- v0.6.2Nov 3, 2026
- v0.6.1Oct 29, 2026
- v0.6.0Oct 25, 2026
- v0.5.3Oct 4, 2026
- v0.5.2Oct 2, 2026
- v0.5.1Sep 28, 2026
- v0.5.0Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分