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
# Download the files
# - crestron_mcp.py
# - requirements.txt
2. Install Dependencies
pip install -r requirements.txt
3. Get Crestron Authorization Token
- Open the Crestron Home mobile app
- Navigate to: Installer Settings → System Control Options → Web API Settings
- Tap Update Token
- Copy the generated authorization token
- 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:
python crestron_mcp.py
For testing or debugging, you can run with a timeout:
timeout 5s python crestron_mcp.py
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
{
"mcpServers": {
"crestron": {
"command": "python",
"args": ["/path/to/crestron_mcp.py"]
}
}
}
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:
{
"host": "192.168.1.100",
"auth_token": "your-token-here"
}
🏠 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 IDdevice_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 IDresponse_format(optional): "markdown" or "json"
crestron_set_shade_position
Control shade positions (0 = closed, 100 = open).
Parameters:
shades(array): List of shade commands withidandposition(0-100)
Example:
{
"shades": [
{"id": 1, "position": 50},
{"id": 2, "position": 100}
]
}
🎬 Scene Control
crestron_list_scenes
List all available scenes with filters.
Parameters:
room_id(optional): Filter by roomscene_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 IDresponse_format(optional): "markdown" or "json"
crestron_set_thermostat_setpoint
Set temperature setpoints.
Parameters:
thermostat_id(integer): Thermostat IDsetpoints(array): List of setpoint commands withtype(Heat/Cool/Auto) andtemperature
Example:
{
"thermostat_id": 15,
"setpoints": [
{"type": "Cool", "temperature": 72},
{"type": "Heat", "temperature": 68}
]
}
crestron_set_thermostat_mode
Set system mode (HEAT, COOL, AUTO, OFF).
Parameters:
thermostats(array): List of thermostat commands withidandmode
crestron_set_thermostat_fan
Set fan mode (AUTO, ON).
Parameters:
thermostats(array): List of thermostat commands withidandmode
📡 Sensors
crestron_get_sensors
Get sensor readings (occupancy, light level, door status, battery).
Parameters:
sensor_id(optional): Specific sensor IDsensor_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 languagepreferred_room_id(optional): Room context for narrowing search
Example:
{
"utterance": "lampadario in soggiorno",
"preferred_room_id": 1
}
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:
- Authenticate:
crestron_authenticatewith host and token - Discover rooms:
crestron_list_roomsto find "soggiorno" room ID - Resolve device:
crestron_resolve_devicewith utterance "lampadario soggiorno" - Get device details: Use returned device_id with
crestron_list_devices - Control device: Set the light level to 0 (implementation depends on device type)
Example 2: Set Morning Scene
User: "Activate the morning scene"
Workflow:
- Authenticate:
crestron_authenticate - List scenes:
crestron_list_scenesto find "Morning" scene - Activate:
crestron_activate_scenewith scene_id
Example 3: Climate Control
User: "Set bedroom thermostat to 72 degrees cool"
Workflow:
- Authenticate:
crestron_authenticate - Find thermostat:
crestron_get_thermostatsorcrestron_resolve_device - Set temperature:
crestron_set_thermostat_setpointwith Cool setpoint at 72 - Set mode:
crestron_set_thermostat_modeto COOL
Example 4: Batch Shade Control
User: "Close all shades in the living room"
Workflow:
- Authenticate:
crestron_authenticate - Find room:
crestron_list_roomsto get living room ID - Find shades:
crestron_list_devicesfiltered by room_id and type "shade" - Control all:
crestron_set_shade_positionwith 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:
- Verify host IP/hostname is correct and reachable
- Regenerate token in Crestron Home app
- Ensure Web API is enabled in Crestron Home settings
- 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:
- Use
crestron_list_devicesto see all available devices - Verify device ID is correct
- Check device is online with
crestron_get_shadesor appropriate status tool
Response Truncated
Problem: Large responses are truncated Solution:
- Use filtering parameters (room_id, device_type)
- Request specific devices by ID
- Use pagination where available
- 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
crestron_mcp.py
├── Constants & Configuration
├── Enums & Models (Pydantic)
├── Session Management
├── Helper Functions
│ ├── authenticate()
│ ├── api_request()
│ ├── format_markdown_list()
│ ├── truncate_response()
│ └── format_device_markdown()
├── Tools (MCP @mcp.tool decorated)
│ ├── Authentication
│ ├── Discovery
│ ├── Shade Control
│ ├── Scene Control
│ ├── Thermostat Control
│ ├── Sensor Monitoring
│ └── Device Resolution
└── Main Entry Point
Testing
Syntax Check:
python -m py_compile crestron_mcp.py
Import Check:
python -c "import crestron_mcp"
Run Server (will wait for MCP client connections):
python crestron_mcp.py
Extending the Server
To add new device types or capabilities:
- Add Pydantic Models: Define input validation models
- Create Tool Function: Use
@mcp.tooldecorator - Implement API Logic: Use helper functions for API calls
- Add Error Handling: Provide clear, actionable error messages
- Format Response: Support both JSON and Markdown formats
- 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.