mcp-server-tuya

A Model Context Protocol (MCP) server that lets AI assistants (Claude, ChatGPT, Copilot, Cursor, and more) control your Tuya / Smart Life smart home devices.

<p align="center">


</p>

Features

- 10 tools for complete device control (on/off, brightness, color, temperature, custom commands)
- Device name resolution — use friendly names like "Living Room Light" instead of IDs
- Intelligent caching — configurable TTL to reduce API calls
- All Tuya regions — EU, US, CN, IN
- Zero config files — credentials via environment variables
- Works with Claude Desktop, ChatGPT, GitHub Copilot, Cursor, Windsurf, Cline, and any MCP-compatible client

Quick Start

1. Get Tuya Credentials

1. Go to Tuya IoT Platform and create an account
2. Create a Cloud Project (select your region and "Smart Home" industry)
3. Go to Devices > Link Tuya App Account and link your Smart Life / Tuya Smart app
4. Copy your Access ID and Access Secret from the project overview

2. Configure your MCP client

<details>
<summary><b>Claude Desktop</b></summary>

Add this to your config file:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tuya": {
      "command": "uvx",
      "args": ["mcp-server-tuya"],
      "env": {
        "TUYA_ACCESS_ID": "your_access_id",
        "TUYA_ACCESS_KEY": "your_access_key",
        "TUYA_API_ENDPOINT": "https://openapi.tuyaeu.com"
      }
    }
  }
}

<details>
<summary><b>Claude Code</b></summary>

claude mcp add tuya -- uvx mcp-server-tuya

Then set your environment variables:

export TUYA_ACCESS_ID="your_access_id"

export TUYA_ACCESS_KEY="your_access_key"

export TUYA_API_ENDPOINT="https://openapi.tuyaeu.com"

<details>
<summary><b>Cursor</b></summary>

Add this to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "tuya": {
      "command": "uvx",
      "args": ["mcp-server-tuya"],
      "env": {
        "TUYA_ACCESS_ID": "your_access_id",
        "TUYA_ACCESS_KEY": "your_access_key",
        "TUYA_API_ENDPOINT": "https://openapi.tuyaeu.com"
      }
    }
  }
}

<details>
<summary><b>VS Code (GitHub Copilot)</b></summary>

Add this to your .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "tuya": {
        "command": "uvx",
        "args": ["mcp-server-tuya"],
        "env": {
          "TUYA_ACCESS_ID": "your_access_id",
          "TUYA_ACCESS_KEY": "your_access_key",
          "TUYA_API_ENDPOINT": "https://openapi.tuyaeu.com"
        }
      }
    }
  }
}

<details>
<summary><b>ChatGPT / Other MCP clients</b></summary>

Any MCP-compatible client can use this server. The general pattern is:
- Command: uvx
- Args: ["mcp-server-tuya"]
- Environment variables: TUYA_ACCESS_ID, TUYA_ACCESS_KEY, TUYA_API_ENDPOINT

Refer to your client's documentation for how to configure MCP servers.
</details>

3. Restart your client

That's it! Ask your AI assistant things like:
- "List all my devices"
- "Turn off the living room light"
- "Set the bedroom light to 50% brightness"
- "What's the temperature in the kitchen?"
- "Turn everything off"

Installation

With uvx (recommended)

No installation needed — uvx runs it directly:

uvx mcp-server-tuya

With pip

pip install mcp-server-tuya

From GitHub

pip install git+https://github.com/juanmartinsantos/mcp-server-tuya.git

Available Tools

| Tool | Description |
|------|-------------|
| tuya_list_devices | List all devices with IDs, names, categories, and online status |
| tuya_get_device_status | Get current device state (power, brightness, temperature, etc.) |
| tuya_get_device_info | Get detailed device info (model, firmware, capabilities) |
| tuya_turn_on_device | Turn on a device (supports multi-switch devices) |
| tuya_turn_off_device | Turn off a device (supports multi-switch devices) |
| tuya_toggle_device | Toggle device on/off |
| tuya_set_brightness | Set light brightness (0-1000) |
| tuya_set_color_temperature | Set color temperature: warm (0) to cool (1000) |
| tuya_set_color | Set RGB color using HSV values |
| tuya_send_command | Send any custom command to a device |

All tools accept either a device ID or a device name (e.g., "Living Room Light").

Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| TUYA_ACCESS_ID | Yes | — | Tuya Cloud API Access ID |
| TUYA_ACCESS_KEY | Yes | — | Tuya Cloud API Access Secret |
| TUYA_API_ENDPOINT | No | https://openapi.tuyaeu.com | API endpoint (see regions below) |
| TUYA_CACHE_TTL | No | 60 | Device list cache duration (seconds) |
| TUYA_REQUEST_TIMEOUT | No | 10 | API request timeout (seconds) |

API Endpoints by Region

| Region | Endpoint |
|--------|----------|
| Europe | https://openapi.tuyaeu.com |
| Americas | https://openapi.tuyaus.com |
| China | https://openapi.tuyacn.com |
| India | https://openapi.tuyain.com |

Local Development

```bash