Tapo MCP

tapo-mcp

通过 Model Context Protocol，将 Tapo 智能家居设备作为可由 AI 调用的工具和资源提供的 MCP 服务。

基于 tapo crate 和 rmcp SDK 构建。以 HTTP 服务运行（Streamable HTTP 传输）。

示例提示词

“列出我的所有 Tapo 设备”

“关掉办公室的灯”

“打开电源排插上的智能插座 4”

“办公室的灯开着吗？”

“将卧室的灯亮度设为 50%”

“将客厅的灯改为珊瑚色”

“从婴儿监视器拍一张快照”

“厨房的温度是多少？”

“显示客厅温湿度传感器过去 24 小时的温度”

“列出智能按钮最近的 5 条事件”

“洗衣机插座本月每天用了多少电？”

“显示电视过去 6 小时的功耗”

工具

工具	描述
list_devices	列出网络中可用的 Tapo 设备（包括设置和获取能力）。
check_device	验证设备 ID 是否与指定 IP 匹配。
get_device_state	获取设备的当前状态（例如 {"type": "DeviceInfo"}）。检查能力的参数，然后运行 check_device。
control_device	按顺序应用 1 到 12 项设置能力来控制设备。检查数量和值，然后运行 check_device；如果设备不支持某项能力，则会在应用任何能力之前失败。
take_snapshot	从 Tapo 摄像头捕获一张 JPEG 静态快照（约 640x360），并以文本形式提供设备 ID、拍摄时间和大小；设置 TAPO_MCP_PUBLIC_URL 后还会提供一个短期有效的链接（参见快照链接）。首先运行 check_device。

资源

URI	描述
tapo://devices	已发现的 Tapo 设备 JSON 列表。

能力

设备和子设备会分别提供其支持的设置能力和获取能力列表。子设备没有自己的 IP；其 ip 是父设备的 IP，应将该 IP 与子设备的 id 一起传入。

设置能力

能力	描述
Brightness	设置设备亮度（1-100）
Color	使用预设名称设置设备颜色
OnOff	打开或关闭设备

获取能力

能力	描述
Detections	读取存储在摄像头 SD 卡上的检测记录及检测到的事件（人物、运动等），最长可追溯 24 小时（C120、C210、C220、C225、C325WB、C520WS、TC40、TC70）
DeviceInfo	读取设备的当前状态
EnergyDataHourly	读取每小时的能耗，单位为 Wh，最长可追溯 8 天（P110、P110M、P115、P304M、P316M）
EnergyDataDaily	读取每天的能耗，单位为 Wh，可追溯一季度（P110、P110M、P115、P304M、P316M）
EnergyDataMonthly	读取每月的能耗，单位为 Wh，可追溯一年（P110、P110M、P115、P304M、P316M）
PowerDataEvery5Minutes	读取每 5 分钟的功率，单位为 W，最长可追溯 12 小时（P110、P110M、P115、P304M、P316M）
PowerDataHourly	读取每小时的功率，单位为 W，最长可追溯 6 天（P110、P110M、P115、P304M、P316M）
Snapshot	拍摄静态 JPEG 快照。由专用的 take_snapshot 工具提供（二进制数据，不是 JSON 状态）
TemperatureHumidityRecords	以 15 分钟为间隔读取过去 24 小时的温度和湿度记录（T310、T315）
TriggerLogs	读取集线器子传感器的分页触发日志（S200、T100、T110、T300）

配置

所有配置均通过以 TAPO_MCP_ 为前缀的环境变量完成：

变量	必填	默认值	描述
TAPO_MCP_USERNAME	是	—	Tapo 账户邮箱
TAPO_MCP_PASSWORD	是	—	Tapo 账户密码
TAPO_MCP_CAMERA_USERNAME	否	—	摄像头账户用户名1。take_snapshot 必需。
TAPO_MCP_CAMERA_PASSWORD	否	—	摄像头账户密码1。take_snapshot 必需。
TAPO_MCP_DISCOVERY_TARGET	是	—	用于发现设备的网络目标（例如 192.168.1.255）
TAPO_MCP_HTTP_ADDR	否	127.0.0.1:3000	服务监听的地址
TAPO_MCP_DISCOVERY_TIMEOUT	否	5	发现超时时间，单位为秒。必须介于 1 和 60 之间2
TAPO_MCP_DISCOVERY_INTERVAL	否	600	后台发现之间的间隔秒数，用于刷新设备列表。必须至少为 TAPO_MCP_DISCOVERY_TIMEOUT，且不超过 86400（一天）2
TAPO_MCP_API_KEY	否	—	用于 HTTP 身份验证的 Bearer 令牌（见下文）
TAPO_MCP_ALLOWED_HOSTS	否	仅限 loopback	以逗号分隔的 Host 请求头允许列表（见网络暴露）
TAPO_MCP_PUBLIC_URL	否	—	客户端访问服务所用的基础 URL（例如 https://tapo.example.com）。启用短时有效的快照链接（见快照链接）

身份验证

设置 TAPO_MCP_API_KEY 后，服务要求所有 HTTP 请求都包含 Authorization: Bearer <key> 请求头。缺少令牌或令牌无效的请求会收到 401 Unauthorized 响应。

如果未设置该变量（或其值为空／仅含空白字符），服务将不启用身份验证。

网络暴露

该服务会执行 MCP Streamable HTTP DNS 重绑定防护。默认情况下，只接受环回 Host 标头（localhost、127.0.0.1、::1），以防止恶意网页通过 DNS 重绑定访问本地运行的服务。向 MCP 端点发送的请求若使用其他 Host，将收到 403 Forbidden 响应。此检查不适用于快照链接（见“快照链接”）。

如需通过局域网或从其他主机访问该服务，请将 TAPO_MCP_ALLOWED_HOSTS 设为客户端连接时使用的确切主机名或 host:port 权限，例如 TAPO_MCP_ALLOWED_HOSTS="tapo-mcp.lan:3000,192.168.1.50:3000"。这会取代默认的环回设置，因此如果仍需要环回访问，也请加入相应条目。

为避免提供未经身份验证的智能家居控制，该服务在绑定到非环回地址（例如 0.0.0.0:3000）且未设置 TAPO_MCP_API_KEY 时会拒绝启动。请设置 API 密钥，或绑定到环回地址。

快照链接

有些 MCP 客户端不会将图像结果传递给模型；另一些客户端会向模型展示图像，却不给模型任何可以交给用户的内容。设置 TAPO_MCP_PUBLIC_URL 后，take_snapshot 还会返回一个 url（以及对应的 expires_at），指向 <TAPO_MCP_PUBLIC_URL>/snapshots/<token>.jpg，这样 Agent 就可以分享链接或下载文件。

• 此链接无需 API 密钥即可访问，因此可以直接在浏览器中打开。TAPO_MCP_ALLOWED_HOSTS 中的 Host 允许列表也不适用于该链接。路径中的随机令牌是唯一的凭据：任何持有该链接的人都可以在链接过期前查看该帧。
• 每个链接的有效期为 5 分钟。快照仅保存在内存中，不会写入磁盘。过期的快照会在 1 分钟内清除，并且最多保留最近的 1024 个快照。
• 如果位于需要身份验证的反向代理（如 Cloudflare Access）之后，在浏览器中打开链接且已登录代理时即可访问。非浏览器请求（如 curl 或 Agent 下载文件）需要代理自身的凭据，或针对 /snapshots/ 的策略例外。

未设置 TAPO_MCP_PUBLIC_URL 时，不会返回链接，也不会提供 /snapshots/ 路由。

OpenTelemetry

将 OTEL_EXPORTER_OTLP_ENDPOINT 设置为 OTLP/HTTP 跟踪端点的完整 URL（包括路径，例如 http://alloy.monitoring:4318/v1/traces），即可导出跟踪数据。OTEL_RESOURCE_ATTRIBUTES 用于添加资源属性。RUST_LOG（默认为 tapo_mcp=info）也会决定导出哪些 span。

跟踪内容：

• 工具调用。 每个 tools/call 请求都会生成一个名为 tools/call <tool> 的服务端 span，覆盖整个调用，并遵循 OpenTelemetry MCP 语义约定。它包含 mcp.method.name、gen_ai.tool.name（仅适用于服务端提供的工具）、gen_ai.operation.name、jsonrpc.request.id、mcp.session.id 和 mcp.protocol.version，以及工具使用这些信息时的 tapo.device.id 和 tapo.device.ip。调用失败时会设置错误状态和 error.type（JSON-RPC 错误代码或 tool_error）。其中，check_device 会跟踪设备验证过程，get_capability、set_capability 或 capture_snapshot 会跟踪设备请求。get_capability 和 set_capability 会包含 tapo.capability，而 control_device 会为其应用的每项 capability 生成一个 set_capability span。步骤失败时会设置错误状态，并将 error.type 设置为失败类型，例如 DeviceNotFound 或 WrongDeviceType。
• 后台任务。 每次发现设备时的 refresh_devices，以及每次清理过期快照链接时的 prune_snapshots。

凭据、API 密钥和图像数据绝不会被记录。工具参数也不会被记录，但 id 和 ip 除外；此外，失败调用的错误消息也会被记录，其中可能会包含被拒绝的值。

系统会遵循传入的 W3C 跟踪上下文。当请求的 params._meta 包含 traceparent（以及可选的 tracestate）时（跟踪调用的 MCP 客户端会发送这些字段），工具调用 span 会成为其子 span，并加入该跟踪。如果承载调用的 HTTP 请求带有 traceparent 标头（例如由跟踪反向代理添加），则会将其记录为 span 链接。若没有 _meta 上下文，则使用 HTTP 标头作为父上下文。两者都没有时，span 会开启一个新跟踪。

部署

Docker

docker run --rm \
  --network host \
  -e TAPO_MCP_USERNAME="[email protected]" \
  -e TAPO_MCP_PASSWORD="<YOUR_TAPO_PASSWORD>" \
  -e TAPO_MCP_CAMERA_USERNAME="<YOUR_CAMERA_ACCOUNT_USERNAME>" \
  -e TAPO_MCP_CAMERA_PASSWORD="<YOUR_CAMERA_ACCOUNT_PASSWORD>" \
  -e TAPO_MCP_DISCOVERY_TARGET="192.168.1.255" \
  -e TAPO_MCP_API_KEY="<YOUR_TAPO_MCP_API_KEY>" \
  ghcr.io/mihai-dinculescu/tapo-mcp:latest

注意： 镜像会绑定到 0.0.0.0:3000，因此必须设置 TAPO_MCP_API_KEY——若未设置，服务拒绝在非回环地址上启动（参见网络暴露）。若要通过主机名或局域网 IP（而非回环地址）访问服务，还需设置 TAPO_MCP_ALLOWED_HOSTS。若要获取快照链接，请添加 -e TAPO_MCP_PUBLIC_URL="https://tapo.example.com"。

注意： 必须使用 --network host，以便容器通过 UDP 广播访问本地网络上的 Tapo 设备进行发现。在 macOS 和 Windows 上不支持 --network host——可以改用 -p 3000:3000，但设备发现将无法工作，因为 Docker Desktop 会在无法访问局域网的虚拟机中运行容器。

Kubernetes

请先创建 Secret 和 ConfigMap：

kubectl create secret generic tapo-mcp-secrets \
  --from-literal=TAPO_MCP_USERNAME="[email protected]" \
  --from-literal=TAPO_MCP_PASSWORD="<YOUR_TAPO_PASSWORD>" \
  --from-literal=TAPO_MCP_CAMERA_USERNAME="<YOUR_CAMERA_ACCOUNT_USERNAME>" \
  --from-literal=TAPO_MCP_CAMERA_PASSWORD="<YOUR_CAMERA_ACCOUNT_PASSWORD>" \
  --from-literal=TAPO_MCP_API_KEY="<YOUR_TAPO_MCP_API_KEY>"

kubectl create configmap tapo-mcp-config \
  --from-literal=TAPO_MCP_DISCOVERY_TARGET="192.168.1.255"

然后应用 Deployment：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tapo-mcp
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: tapo-mcp
  template:
    metadata:
      labels:
        app: tapo-mcp
    spec:
      hostNetwork: true
      containers:
        - name: tapo-mcp
          image: ghcr.io/mihai-dinculescu/tapo-mcp:latest
          env:
            - name: TAPO_MCP_USERNAME
              valueFrom:
                secretKeyRef:
                  name: tapo-mcp-secrets
                  key: TAPO_MCP_USERNAME
            - name: TAPO_MCP_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: tapo-mcp-secrets
                  key: TAPO_MCP_PASSWORD
            - name: TAPO_MCP_CAMERA_USERNAME
              valueFrom:
                secretKeyRef:
                  name: tapo-mcp-secrets
                  key: TAPO_MCP_CAMERA_USERNAME
            - name: TAPO_MCP_CAMERA_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: tapo-mcp-secrets
                  key: TAPO_MCP_CAMERA_PASSWORD
            - name: TAPO_MCP_API_KEY
              valueFrom:
                secretKeyRef:
                  name: tapo-mcp-secrets
                  key: TAPO_MCP_API_KEY
            - name: TAPO_MCP_DISCOVERY_TARGET
              valueFrom:
                configMapKeyRef:
                  name: tapo-mcp-config
                  key: TAPO_MCP_DISCOVERY_TARGET

注意： UDP 广播发现需要设置 hostNetwork: true，这与 Docker 中的 --network host 类似。由于客户端通过节点 IP 或主机名（而非回环地址）访问服务，请相应设置 TAPO_MCP_ALLOWED_HOSTS（参见网络暴露）。若要获取快照链接，请将 TAPO_MCP_PUBLIC_URL 添加到 ConfigMap 和 Deployment 的 env 中。

OpenClaw

OpenClaw 的 tapo skill 可让 OpenClaw Agent 轻松使用已部署的 tapo MCP 服务。

使用以下命令安装：

npx clawhub install tapo

贡献

欢迎并鼓励贡献！请参阅 /tapo-mcp/CONTRIBUTING.md。

Footnotes

1. 在 Tapo 应用中，为每台摄像头前往“摄像头设置 > 高级设置 > 摄像头账户”进行设置。此账户不同于 TP-Link 云账户。 ↩ ↩²

2. 后台发现运行期间，联系设备的工具调用会等待其完成，而发现过程也会等待正在进行的调用结束。一次运行耗时约为 TAPO_MCP_DISCOVERY_TIMEOUT 秒，此外还需花费一些时间登录设备；如果设备响应缓慢，耗时会更长。间隔较短意味着这些暂停会频繁发生：使用默认超时时间并将间隔设为 15 时，每 15 秒中工具调用可能会被阻塞数秒。list_devices 和 tapo://devices 资源不会等待。 ↩ ↩²