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

已驗證STDIO僅桌面位置與生活安全與監控

概覽

AI 產生的概覽

此 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。
安裝前請注意
會保存 Tapo 帳號與攝影機憑證,應以機密方式管理。control_device 會改變真實裝置狀態,包括燈具與插座。Docker 映像監聽所有網路介面,未設定 TAPO_MCP_API_KEY 時會拒絕啟動;用戶端需以 Authorization 標頭帶上此權杖。透過 TAPO_MCP_PUBLIC_URL 提供的快照連結不受 API 金鑰與 Host 允許清單限制,任何取得連結的人都能在到期前查看畫面。選用的 OTLP 追蹤會將工具呼叫 span 傳送到收集端。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Tapo MCP,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

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

ToolDescription
list_devicesList available Tapo devices on the network (includes set and get capabilities).
get_device_stateGet a device's current state (e.g. {"type": "DeviceInfo"}). Checks the capability's parameters, then verifies the device ID matches at the given IP.
control_deviceControl a device by applying 1 to 12 set capabilities, in order. Checks the count and values, then verifies the device ID matches at the given IP; a capability the device does not support fails before any is applied. Returns the device's state afterwards, read back from the device.
take_snapshotCapture a still JPEG snapshot from a Tapo camera (~640x360), with the device id, capture time and size as text, plus a short-lived link when TAPO_MCP_PUBLIC_URL is set (see Snapshot links). Verifies the device ID matches at the given IP first.

Resources

URIDescription
tapo://devicesJSON list of discovered Tapo devices.

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

CapabilityDescription
BrightnessSet the device brightness (1-100)
ColorSet the device color using a preset name
HueSaturationSet the device color using a hue (0-360) and saturation (1-100)
ColorTemperatureSet the device color temperature (2500-6500)
OnOffTurn the device on or off

Get Capabilities

CapabilityDescription
DetectionsRead the detections stored on a camera's SD card, with the events detected (person, motion, ...), for up to 24 hours (C120, C210, C220, C225, C325WB, C520WS, TC40, TC70)
DeviceInfoRead the device's current state
EnergyDataHourlyRead the energy used per hour, in Wh, for up to 8 days (P110, P110M, P115, P304M, P316M)
EnergyDataDailyRead the energy used per day, in Wh, for a quarter of a year (P110, P110M, P115, P304M, P316M)
EnergyDataMonthlyRead the energy used per month, in Wh, for a year (P110, P110M, P115, P304M, P316M)
EnergyMeterDataRead the live voltage, current and power, and the energy used since the device last restarted (P110, P110M, P115, P304M, P316M)
PowerDataEvery5MinutesRead the power draw every 5 minutes, in W, for up to 12 hours (P110, P110M, P115, P304M, P316M)
PowerDataHourlyRead the power draw every hour, in W, for up to 6 days (P110, P110M, P115, P304M, P316M)
SnapshotCapture a still JPEG snapshot. Served by the dedicated take_snapshot tool (binary, not JSON state)
TemperatureHumidityRecordsRead the last 24 hours of temperature and humidity records (T310, T315) at 15 minute intervals
TriggerLogsRead paginated trigger logs from a hub child sensor (S200, T100, T110, T300)

Configuration

All configuration is via environment variables prefixed with TAPO_MCP_:

VariableRequiredDefaultDescription
TAPO_MCP_USERNAMEYes—Tapo account email
TAPO_MCP_PASSWORDYes—Tapo account password
TAPO_MCP_CAMERA_USERNAMENo—Camera account username1. Required by take_snapshot.
TAPO_MCP_CAMERA_PASSWORDNo—Camera account password1. Required by take_snapshot.
TAPO_MCP_DISCOVERY_TARGETYes—IP address for device discovery, usually the network's broadcast address (e.g. 192.168.1.255)
TAPO_MCP_HTTP_ADDRNo127.0.0.1:3000Address the server listens on
TAPO_MCP_DISCOVERY_TIMEOUTNo5Discovery timeout in seconds. Must be between 1 and 602
TAPO_MCP_DISCOVERY_INTERVALNo600Seconds between background discoveries that refresh the device list. Must be at least TAPO_MCP_DISCOVERY_TIMEOUT and at most 86400 (one day)2
TAPO_MCP_API_KEYNo—Bearer token for HTTP authentication (see below)
TAPO_MCP_ALLOWED_HOSTSNoloopback onlyComma-separated Host header allowlist (see Network exposure)
TAPO_MCP_PUBLIC_URLNo—Base URL clients reach the server at (e.g. https://tapo.example.com). Enables short-lived snapshot links (see Snapshot links)

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 Host allowlist from TAPO_MCP_ALLOWED_HOSTS does 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/call request gets one server span named tools/call <tool>, covering the whole call, following the OpenTelemetry MCP semantic conventions. It carries mcp.method.name, gen_ai.tool.name (only for tools the server provides), gen_ai.operation.name, jsonrpc.request.id, mcp.session.id and mcp.protocol.version, plus tapo.device.id and tapo.device.ip where the tool takes them. A failed call has error status and error.type (the JSON-RPC error code, or tool_error). Inside it, the check_device span covers the verification that the device ID matches at the given IP, and get_capability, set_capability or capture_snapshot covers the device request. get_capability and set_capability carry tapo.capability, and control_device has one set_capability span for each capability it applies, then a get_capability span for the device info it reads back. A failed step has error status and error.type set to the kind of failure, such as DeviceNotFound or WrongDeviceType.
  • Background jobs. refresh_devices for each device discovery, and prune_snapshots for 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

bash
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

Note: The image binds to 0.0.0.0:3000, so TAPO_MCP_API_KEY is 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 set TAPO_MCP_ALLOWED_HOSTS. To get snapshot links, add -e TAPO_MCP_PUBLIC_URL="https://tapo.example.com".

Note: --network host is required so the container can reach Tapo devices on your local network via UDP broadcast for discovery. On macOS and Windows, --network host is not supported — you can use -p 3000:3000 instead, but device discovery won't work as Docker Desktop runs containers inside a VM without LAN access.

Kubernetes

Create the Secret and ConfigMap first:

bash
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"

Then apply the Deployment:

yaml
apiVersion: apps/v1kind: Deploymentmetadata:  name: tapo-mcpspec:  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          livenessProbe:            httpGet:              path: /livez              port: 3000            periodSeconds: 30          resources:            requests:              cpu: 10m              memory: 32Mi            limits:              memory: 256Mi

Note: hostNetwork: true is required for UDP broadcast discovery, similar to --network host in Docker. Because clients reach the server by node IP or hostname rather than loopback, set TAPO_MCP_ALLOWED_HOSTS accordingly (see Network exposure). To get snapshot links, add TAPO_MCP_PUBLIC_URL to the ConfigMap and the Deployment's env.

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:

bash
npx clawhub install tapo

Contributing

Contributions are welcome and encouraged! See /tapo-mcp/CONTRIBUTING.md.

Footnotes

  1. Set on each camera in the Tapo app under Camera Settings > Advanced Settings > Camera Account. Distinct from your TP-Link cloud account. ↩ ↩2

  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_TIMEOUT seconds 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: at 15 with the default timeout, tool calls can be held up for several seconds out of every 15. list_devices and the tapo://devices resource never wait. ↩ ↩2

來源:tapo-mcp/README.md,提交 7cc850d

工具

0
SourceWeft 曾在隔離沙箱中以無憑證方式啟動該軟體包一次,以列出其工具,但未能完成:該軟體包類型無法在沙箱中執行。

版本歷史

8
  1. v0.7.0最新Nov 12, 2026
  2. v0.6.2Nov 3, 2026
  3. v0.6.1Oct 29, 2026
  4. v0.6.0Oct 25, 2026
  5. v0.5.3Oct 4, 2026
  6. v0.5.2Oct 2, 2026
  7. v0.5.1Sep 28, 2026
  8. v0.5.0Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分