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"> <img src="https://img.shields.io/badge/MCP-Compatible-green?style=for-the-badge" alt="MCP Compatible" /> <img src="https://img.shields.io/badge/Tuya-Smart%20Home-orange?style=for-the-badge" alt="Tuya Smart Home" /> </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>

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

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

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

<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

# Clone the repository
git clone https://github.com/juanmartinsantos/mcp-server-tuya.git
cd mcp-server-tuya

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # macOS/Linux

# Install in editable mode
pip install -e ".[dev]"

# Copy and configure environment
cp .env.example .env
# Edit .env with your credentials

# Run the server
mcp-server-tuya
# or: python -m mcp_server_tuya

Troubleshooting

"TUYA_ACCESS_ID environment variable is required"

Your credentials are not set. Make sure you've added the env section to your MCP client config.

"API error: permission deny"

Your Tuya Cloud project doesn't have the right permissions. Go to Tuya IoT Platform > your project > Service API and enable IoT Core and Smart Home APIs.

"Device not found"

The device name doesn't match. Use tuya_list_devices first to see the exact names of your devices.

Server won't start

Make sure you have uv installed. Install it with:

# Windows
winget install --id=astral-sh.uv

# macOS
brew install uv

License

MIT License - see LICENSE for details.

Credits

• FastMCP — Pythonic MCP server framework
• tuya-connector-python — Official Tuya Cloud SDK
• Model Context Protocol — by Anthropic