Tuya Infrared MCP Server

English | 中文

A Model Context Protocol (MCP) server that allows AI assistants to control devices through Tuya infrared remote control.

Features

• 🎮 Control devices via Tuya infrared remote control
• 🔌 MCP protocol support (Streamable HTTP)
• 🌐 RESTful API with health check endpoint
• ⚙️ Easy configuration via environment variables
• 🔒 Secure credential management

Prerequisites

• Node.js >= 14.0.0
• Tuya IoT Platform account
• Tuya infrared remote control device
• Learned IR codes for your target device

Quick Start

1. Install Dependencies

npm install

2. Configure Environment Variables

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Edit .env:

TUYA_BASE_URL=https://openapi.tuyacn.com
TUYA_ACCESS_ID=your_access_id_here
TUYA_ACCESS_SECRET=your_access_secret_here
TUYA_DEVICE_ID=your_device_id_here
TUYA_REMOTE_ID=your_remote_id_here
TUYA_CATEGORY_ID=13
KEY_SWITCH=your_switch_key_here
KEY_MODE_15MIN=your_mode_key_here
PORT=3036

3. Run Server

npm start

Server will run on http://localhost:3036

How to Get Tuya Credentials

Step 1: Create Tuya IoT Platform Account

1. Go to Tuya IoT Platform
2. Register and create a new project
3. Choose "Custom Development"
4. Select data center (e.g., China)

Step 2: Get API Credentials

1. Go to your project dashboard
2. Navigate to "Overview" → "Authorization Key"
3. Copy Access ID and Access Secret

Step 3: Enable Infrared API Service

1. Go to "Service API" tab
2. Search for "Infrared Remote Control" (万能红外开放能力)
3. Enable the service

Step 4: Link Your Device

1. Add your Tuya infrared remote to Tuya Smart App
2. Go to project "Devices" tab
3. Click "Link Tuya App Account"
4. Link your Tuya Smart App account
5. Your device will appear in the device list

Step 5: Get Device Information

Use the test script to get device info:

const { TuyaContext } = require('@tuya/tuya-connector-nodejs');

const context = new TuyaContext({
  baseUrl: 'https://openapi.tuyacn.com',
  accessKey: 'your_access_id',
  secretKey: 'your_access_secret'
});

// Get device list
const devices = await context.request({
  path: '/v1.0/devices',
  method: 'GET'
});

console.log(devices);

Step 6: Learn IR Codes

1. Use Tuya Smart App to learn IR codes from your device's remote
2. Use API to get learned keys:

// Get remote list
const remotes = await context.request({
  path: `/v1.0/infrareds/${DEVICE_ID}/remotes`,
  method: 'GET'
});

// Get learned keys for a remote
const keys = await context.request({
  path: `/v1.0/infrareds/${DEVICE_ID}/remotes/${REMOTE_ID}/keys`,
  method: 'GET'
});

console.log(keys);

MCP Configuration

For Claude Desktop / Claude Code

Add to your MCP configuration file:

{
  "mcpServers": {
    "tuya-infrared": {
      "transport": {
        "type": "streamable-http",
        "url": "http://localhost:3036/mcp"
      }
    }
  }
}

For Remote Access

If running on a server:

{
  "mcpServers": {
    "tuya-infrared": {
      "transport": {
        "type": "streamable-http",
        "url": "http://your-server-ip:3036/mcp"
      }
    }
  }
}

Note: Make sure to open port 3036 in your firewall.

API Endpoints

Health Check

GET /health

Response:

{
  "status": "ok",
  "service": "tuya-infrared-mcp"
}

MCP Endpoint

POST /mcp
Content-Type: application/json

Available MCP Tools

send_infrared

Send infrared signal to control your device.

Parameters:

• action (string): Action type
  • switch: Toggle power switch
  • mode_15min: Change to 15-minute mode

Example:

// In AI assistant
send_infrared({ action: "switch" })
send_infrared({ action: "mode_15min" })

Limitations

• Infrared signal requires line-of-sight
• Distance limitation (typically 1-3 meters)
• Remote control must be powered on
• Cannot work through walls or obstacles

Troubleshooting

"Sign Invalid" Error

• Check if your Access Secret is correct
• Make sure you linked your Tuya Smart App account to the project

"API Not Subscribed" Error

• Enable "Infrared Remote Control" service in your project

Connection Timeout

• Check if port 3036 is open
• Verify server is running
• Check firewall settings

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Built with Tuya IoT Platform
• Based on Model Context Protocol