mcp-server-tuya
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-tuya Turn off the living room light"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Go to Tuya IoT Platform and create an account
Create a Cloud Project (select your region and "Smart Home" industry)
Go to Devices > Link Tuya App Account and link your Smart Life / Tuya Smart app
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.jsonmacOS:
~/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-tuyaThen 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:
uvxArgs:
["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
With uvx (recommended)
No installation needed — uvx runs it directly:
uvx mcp-server-tuyaWith pip
pip install mcp-server-tuyaFrom GitHub
pip install git+https://github.com/juanmartinsantos/mcp-server-tuya.gitAvailable Tools
Tool | Description |
| List all devices with IDs, names, categories, and online status |
| Get current device state (power, brightness, temperature, etc.) |
| Get detailed device info (model, firmware, capabilities) |
| Turn on a device (supports multi-switch devices) |
| Turn off a device (supports multi-switch devices) |
| Toggle device on/off |
| Set light brightness (0-1000) |
| Set color temperature: warm (0) to cool (1000) |
| Set RGB color using HSV values |
| 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 |
| Yes | — | Tuya Cloud API Access ID |
| Yes | — | Tuya Cloud API Access Secret |
| No |
| API endpoint (see regions below) |
| No |
| Device list cache duration (seconds) |
| No |
| API request timeout (seconds) |
API Endpoints by Region
Region | Endpoint |
Europe |
|
Americas |
|
China |
|
India |
|
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_tuyaTroubleshooting
"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 uvLicense
MIT License - see LICENSE for details.
Credits
FastMCP — Pythonic MCP server framework
tuya-connector-python — Official Tuya Cloud SDK
Model Context Protocol — by Anthropic
Available Tools
10 toolstuya_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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Control your Tesla from your AI assistant - climate, charging, access, and security.
Control your existing Philips lights, Sonos speakers, Roborock vacuums and other supported devices through Port OS cloud. Give ChatGPT, Claude and other MCP-compatible assistants access to the devices you connect. Turn off the living room lights, play music on your speakers, adjust the thermostat, run a vacuum in a room, check a camera snapshot or find a connected tracker. Available actions depend on your linked provider accounts and each device’s supported capabilities. Port OS runs in the cloud; no local server is required. You choose the account, device and capability permissions each assistant receives. Device operations require user OAuth; public tool discovery does not grant device access. Port OS is in alpha. Setup: https://portoperatingsystem.com/docs/getting-started/ Support: https://portoperatingsystem.com/contact/
Control and query Heiman smart home devices: lights, AC, curtains, climate, logs and scenes.
Image and video AI tools and your own pipelines, run from any AI assistant.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides tools for AI assistants to interact with smart home devices through Home Assistant, allowing operations like checking entity states and calling services.33MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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.1MIT
- AlicenseAqualityDmaintenanceEnables 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.91MIT
- FlicenseNot gradedqualityDmaintenanceEnables LLMs to control Home Assistant devices, including lights, switches, and climate devices, through natural language commands.-