Skip to main content
Glama

mcp-server-tuya

PyPI version Python License: MIT

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

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

Related MCP server: Home Assistant MCP Server

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

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

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

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

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.

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

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

Available Tools

10 tools
tuya_get_device_infoA

Get detailed information about a specific Tuya device by device_id or name (e.g. 'Living Room Light'), including capabilities, category, model and firmware version

Inputs: device_id (required). Returns: result

tuya_get_device_statusA

Get the current status of a specific Tuya device by device_id or name (e.g. 'Living Room Light'), including power state, brightness, color, temperature and other properties

Inputs: device_id (required). Returns: result

tuya_list_devicesA

Get a list of all available Tuya devices with their IDs, names, categories, and online status

Inputs: no named parameters. Returns: result

tuya_send_commandA

Send custom commands to a Tuya device by device_id or name (e.g. 'Living Room Light'). commands must be a JSON string like: [{"code": "switch_1", "value": true}]

Inputs: commands (required), device_id (required). Returns: result

tuya_set_brightnessA

Set the brightness of a Tuya light by device_id or name (e.g. 'Living Room Light'). brightness must be between 0 (minimum) and 1000 (maximum)

Inputs: device_id (required), brightness (required). Returns: result

tuya_set_colorB

Set the color of a Tuya RGB light by device_id or name (e.g. 'Living Room Light') using HSV values. hue: 0-360, saturation: 0-255, value: 0-255

Inputs: hue (required), value (required), device_id (required), saturation (required). Returns: result

tuya_set_color_temperatureA

Set the color temperature of a Tuya light by device_id or name (e.g. 'Living Room Light'). temperature must be between 0 (warm white) and 1000 (cool white)

Inputs: device_id (required), temperature (required). Returns: result

tuya_toggle_deviceA

Toggle a Tuya device on/off by device_id or name (e.g. 'Living Room Light'). Turns it on if off, turns it off if on

Inputs: device_id (required), switch_code. Returns: result

tuya_turn_off_deviceA

Turn off a Tuya device by device_id or name (e.g. 'Living Room Light'). For devices with multiple switches, specify switch_code (switch_1, switch_2, etc.)

Inputs: device_id (required), switch_code. Returns: result

tuya_turn_on_deviceA

Turn on a Tuya device by device_id or name (e.g. 'Living Room Light'). For devices with multiple switches, specify switch_code (switch_1, switch_2, etc.)

Inputs: device_id (required), switch_code. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools are clearly distinct (list, get status, get info, turn on/off, toggle, set brightness/color temp/color, send command). However, get_device_status and get_device_info could be confused at first glance, though their descriptions clarify the difference.

    Naming Consistency4/5

    All tools follow a tuya_<verb>_<noun> pattern in snake_case, which is consistent. Minor deviation: set_brightness, set_color_temperature, and set_color omit the 'device' suffix seen in most other control verbs, but this does not harm readability.

    Tool Count5/5

    10 tools is well within the ideal 3-15 range. Each tool covers a distinct operation for smart home control (discovery, status, metadata, on/off, toggling, light settings, and custom commands), so none feel redundant.

    Completeness5/5

    The tool surface covers the full lifecycle of device interaction: discovering devices (list), reading state (status/info), controlling power (on/off/toggle), adjusting light properties (brightness, color temp, color), and arbitrary customization via send_command. This is complete for a smart home control server.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Home Assistant smart home devices through natural language. Control devices, manage automations, query entity states, and retrieve historical data across your home automation system.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to control Govee smart devices, including lights, via natural language. Supports turning on/off, changing colors, adjusting brightness, and activating scenes through the Govee API or local network.
      9
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to control Home Assistant devices, including lights, switches, and climate devices, through natural language commands.
      -