Crestron Home MCP Server

A production-ready Model Context Protocol (MCP) server for controlling Crestron Home automation systems. This server enables LLMs to discover and control Crestron devices including lights, shades, scenes, thermostats, sensors, and more through natural language.

Features

✨ Comprehensive Device Control

• Rooms & Devices: Full discovery of rooms and all device types

• Shades/Blinds: Position control (0-100%), batch operations

• Scenes: List and activate pre-configured scenes

• Thermostats: Complete climate control (temperature, mode, fan, schedule)

• Sensors: Read occupancy, light, door, and battery status

• Natural Language Resolution: Fuzzy matching for device names in any language

🛡️ Production-Ready Features

• Session Management: Automatic authentication with 10-minute session handling

• Error Handling: Comprehensive error messages with actionable guidance

• Character Limits: Smart truncation with helpful pagination guidance

• Batch Operations: Control multiple devices simultaneously

• Multi-format Output: JSON and Markdown response formats

• SSL Support: Handles self-signed certificates from Crestron systems

🌍 Multi-Language Support

• Italian: "Spegni la luce del lampadario in soggiorno"

• English: "Turn off the living room chandelier"

• Any language: Natural language device resolution with confidence scoring

Requirements

• Python 3.10 or higher

• Crestron Home system with REST API enabled

• Network access to Crestron Home system

• Authorization token from Crestron Home app

Installation

1. Clone or Download

2. Install Dependencies

3. Get Crestron Authorization Token

1. Open the Crestron Home mobile app

2. Navigate to: Installer Settings → System Control Options → Web API Settings

3. Tap Update Token

4. Copy the generated authorization token

5. Save it securely - you'll need it for authentication

Usage

Running the MCP Server

The server uses stdio transport by default, which is suitable for integration with MCP clients:

For testing or debugging, you can run with a timeout:

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Available Tools

🔐 Authentication

crestron_authenticate

Establish session with Crestron Home system. Must be called first before any other operations.

Parameters:

• host (string): Crestron Home IP or hostname (e.g., "192.168.1.100")

• auth_token (string): Authorization token from Crestron Home app

Example:

🏠 Discovery

crestron_list_rooms

Get all rooms configured in the system.

Parameters:

• response_format (optional): "markdown" (default) or "json"

crestron_list_devices

Discover all devices with filtering options.

Parameters:

• room_id (optional): Filter by room ID

• device_type (optional): Filter by type (light, shade, thermostat, sensor, etc.)

• response_format (optional): "markdown" or "json"

🪟 Shade Control

crestron_get_shades

Get current shade positions and status.

Parameters:

• shade_id (optional): Specific shade ID

• response_format (optional): "markdown" or "json"

crestron_set_shade_position

Control shade positions (0 = closed, 100 = open).

Parameters:

• shades (array): List of shade commands with id and position (0-100)

Example:

🎬 Scene Control

crestron_list_scenes

List all available scenes with filters.

Parameters:

• room_id (optional): Filter by room

• scene_type (optional): Filter by type (Lighting, Shade, Media, Climate, etc.)

• response_format (optional): "markdown" or "json"

crestron_activate_scene

Activate a scene by ID.

Parameters:

• scene_id (integer): Scene ID to activate

🌡️ Thermostat Control

crestron_get_thermostats

Get thermostat status and capabilities.

Parameters:

• thermostat_id (optional): Specific thermostat ID

• response_format (optional): "markdown" or "json"

crestron_set_thermostat_setpoint

Set temperature setpoints.

Parameters:

• thermostat_id (integer): Thermostat ID

• setpoints (array): List of setpoint commands with type (Heat/Cool/Auto) and temperature

Example:

crestron_set_thermostat_mode

Set system mode (HEAT, COOL, AUTO, OFF).

Parameters:

• thermostats (array): List of thermostat commands with id and mode

crestron_set_thermostat_fan

Set fan mode (AUTO, ON).

Parameters:

• thermostats (array): List of thermostat commands with id and mode

📡 Sensors

crestron_get_sensors

Get sensor readings (occupancy, light level, door status, battery).

Parameters:

• sensor_id (optional): Specific sensor ID

• sensor_subtype (optional): Filter by subtype (OccupancySensor, PhotoSensor, DoorSensor)

• response_format (optional): "markdown" or "json"

🔍 Device Resolution

crestron_resolve_device

Resolve natural language descriptions to specific devices using fuzzy matching.

Parameters:

• utterance (string): Natural language device description in any language

• preferred_room_id (optional): Room context for narrowing search

Example:

Returns:

• High confidence (≥0.8): Single resolved device

• Low confidence (<0.8): Multiple candidates requiring clarification

Workflow Examples

Example 1: Italian User Command

User: "Spegni la luce del lampadario in soggiorno" (Turn off the living room chandelier)

Workflow:

1. Authenticate: crestron_authenticate with host and token

2. Discover rooms: crestron_list_rooms to find "soggiorno" room ID

3. Resolve device: crestron_resolve_device with utterance "lampadario soggiorno"

4. Get device details: Use returned device_id with crestron_list_devices

5. Control device: Set the light level to 0 (implementation depends on device type)

Example 2: Set Morning Scene

User: "Activate the morning scene"

Workflow:

1. Authenticate: crestron_authenticate

2. List scenes: crestron_list_scenes to find "Morning" scene

3. Activate: crestron_activate_scene with scene_id

Example 3: Climate Control

User: "Set bedroom thermostat to 72 degrees cool"

Workflow:

1. Authenticate: crestron_authenticate

2. Find thermostat: crestron_get_thermostats or crestron_resolve_device

3. Set temperature: crestron_set_thermostat_setpoint with Cool setpoint at 72

4. Set mode: crestron_set_thermostat_mode to COOL

Example 4: Batch Shade Control

User: "Close all shades in the living room"

Workflow:

1. Authenticate: crestron_authenticate

2. Find room: crestron_list_rooms to get living room ID

3. Find shades: crestron_list_devices filtered by room_id and type "shade"

4. Control all: crestron_set_shade_position with all shade IDs at position 0

Architecture

Session Management

• 10-minute session timeout with 1-minute buffer

• Automatic session validation before each API call

• Clear error messages when re-authentication needed

Error Handling

• Comprehensive HTTP error handling with status codes

• Actionable error messages guide users to solutions

• Graceful handling of authentication failures and timeouts

Response Formats

Markdown Format (default):

• Human-readable with headers and formatting

• Optimized for display to users

• Includes helpful context and summaries

JSON Format:

• Machine-readable structured data

• Complete field inclusion for programmatic processing

• Consistent schema across all tools

Character Limits

• 25,000 character response limit

• Smart truncation with clear indicators

• Helpful guidance on filtering and pagination

API Reference

Crestron Home REST API

Base URL: https://{host}/cws/api

Authentication:

• Header: Crestron-RestAPI-AuthKey: {session_key}

• Session lifetime: 10 minutes

• All systems use self-signed SSL certificates

Supported Endpoints:

• /login - Authentication

• /rooms - Room discovery

• /devices - Device discovery

• /shades - Shade control and status

• /shades/SetState - Shade position control

• /scenes - Scene discovery

• /scenes/recall/{id} - Scene activation

• /thermostats - Thermostat status

• /thermostats/SetPoint - Temperature control

• /thermostats/mode - System mode control

• /thermostats/fanmode - Fan control

• /sensors - Sensor readings

Troubleshooting

Authentication Issues

Problem: "Not authenticated or session expired" Solution: Call crestron_authenticate first with valid host and token

Problem: "Authentication failed" Solutions:

1. Verify host IP/hostname is correct and reachable

2. Regenerate token in Crestron Home app

3. Ensure Web API is enabled in Crestron Home settings

4. Check network connectivity

SSL Certificate Warnings

Problem: SSL verification warnings Solution: The server automatically handles self-signed certificates. This is expected behavior for Crestron systems.

Device Not Found

Problem: "Device with ID X not found" Solution:

1. Use crestron_list_devices to see all available devices

2. Verify device ID is correct

3. Check device is online with crestron_get_shades or appropriate status tool

Response Truncated

Problem: Large responses are truncated Solution:

1. Use filtering parameters (room_id, device_type)

2. Request specific devices by ID

3. Use pagination where available

4. Choose JSON format for more compact output

Security Considerations

Token Storage

• Never commit authorization tokens to version control

• Store tokens securely (environment variables, secure vaults)

• Rotate tokens periodically in Crestron Home app

Network Security

• Use VPN when accessing Crestron systems remotely

• Implement IP whitelisting on Crestron system if available

• Monitor API access logs

Session Security

• Sessions expire after 10 minutes automatically

• Re-authenticate for each session

• Monitor for unauthorized access attempts

Development

Code Structure

Testing

Syntax Check:

Import Check:

Run Server (will wait for MCP client connections):

Extending the Server

To add new device types or capabilities:

1. Add Pydantic Models: Define input validation models

2. Create Tool Function: Use @mcp.tool decorator

3. Implement API Logic: Use helper functions for API calls

4. Add Error Handling: Provide clear, actionable error messages

5. Format Response: Support both JSON and Markdown formats

6. Update Documentation: Add to this README

Performance

• Async/await: All I/O operations are async for optimal performance

• Connection Pooling: Single HTTP client instance reused across requests

• Session Caching: Authentication key cached for session lifetime

• Batch Operations: Support for controlling multiple devices in single API call

Limitations

API Limitations

• Camera control not available in Crestron Home REST API

• Light control endpoints not explicitly documented (use device discovery)

• Door lock control endpoints not explicitly documented

• Media room control endpoints not explicitly documented

• No WebSocket/event streaming (polling required for real-time updates)

MCP Server Limitations

• Stdio transport only (HTTP/SSE not configured)

• Single concurrent session per server instance

• No rate limiting implemented (respects Crestron system limits)

Contributing

This is a production-ready implementation following MCP best practices. Contributions welcome for:

• Additional device type support (lights, locks, media rooms)

• Enhanced device resolution algorithms

• Rate limiting and request queuing

• WebSocket event support (if added to Crestron API)

• Additional transport options (HTTP, SSE)

License

[Your License Here]

Support

For issues related to:

• MCP Server: Review error messages and logs

• Crestron API: Consult Crestron Home REST API documentation

• Device Control: Verify device IDs and capabilities with discovery tools

• Authentication: Check token validity and network connectivity

Acknowledgments

Built with:

• MCP Python SDK - FastMCP framework

• httpx - Async HTTP client

• Pydantic - Data validation

Based on the Crestron Home REST API specification and MCP best practices for building high-quality LLM integrations.