# Lutron Caseta MCP Server
A Model Context Protocol (MCP) server for controlling Lutron Caseta smart lights and devices. Powered by [pylutron-caseta](https://github.com/gurumitts/pylutron-caseta). This server allows AI assistants to interact with your Lutron Caseta bridge to control lights, check device status, and manage your smart home lighting.
## Features
- **Device Control**: Turn lights on/off and set dimmer levels
- **Device Discovery**: List all lights and devices connected to your bridge
- **Hybrid Pairing**: Support for both standalone pairing utility and MCP tool-based pairing
- **Type Safety**: Full type hints for better development experience
- **Error Handling**: Robust error handling with clear error messages
## Prerequisites
- Python 3.10 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- Lutron Caseta bridge connected to your network
- Network access to your Lutron Caseta bridge
No manual installation required - `uv` will handle everything automatically when you configure Claude Desktop.
## Setup
### 1. Find Your Bridge IP Address
You need to find the IP address of your Lutron Caseta bridge on your network. You can:
- Check your router's device list
- Use a network scanner app
- Check the Lutron Caseta app settings
### 2. Pair with Your Bridge
You have two options for pairing:
#### Option A: MCP Tool Pairing (Recommended)
Start the MCP server and use the `pair_bridge_tool` through Claude. Simply ask Claude to "pair with my Lutron bridge at 192.168.1.100" and Claude will guide you through the process.
#### Option B: Standalone Pairing Utility
```bash
# Run the pairing utility
uv run --with lutron-caseta-mcp lutron-caseta-pair 192.168.1.100
# Or specify a custom directory for certificates
uv run --with lutron-caseta-mcp lutron-caseta-pair 192.168.1.100 ./certificates
```
**For both options:**
1. When prompted, press the small black button on the back of your Lutron Caseta bridge
2. You have 30 seconds to press the button after the prompt appears
3. Three certificate files will be created:
- `caseta-bridge.crt` (CA certificate)
- `caseta.crt` (Client certificate)
- `caseta.key` (Private key)
### 3. Configure Environment Variables
Set the required environment variables:
```bash
export LUTRON_BRIDGE_IP=192.168.1.100
export LUTRON_CERT_DIR=./certificates # Optional, defaults to current directory
```
## Usage
### Available MCP Tools
The server provides the following tools that can be called by MCP clients:
#### `pair_bridge_tool(host: str, output_dir: str = ".")`
Pair with a Lutron Caseta bridge and save certificates.
**Parameters:**
- `host`: IP address of the bridge
- `output_dir`: Directory to save certificate files (optional)
**Returns:**
- Success status, message, and certificate file paths
#### `check_connection()`
Check connection status and certificate files.
**Returns:**
- Bridge IP, certificate directory, certificate status, and connection status
#### `list_devices(domain: str = "light")`
List all devices in the specified domain.
**Parameters:**
- `domain`: Device domain to list (default: "light")
**Returns:**
- List of devices with their IDs, names, and capabilities
#### `turn_on_device(device_id: str)`
Turn on a device by ID.
**Parameters:**
- `device_id`: The device ID to turn on
**Returns:**
- Device ID, action performed, and success status
#### `turn_off_device(device_id: str)`
Turn off a device by ID.
**Parameters:**
- `device_id`: The device ID to turn off
**Returns:**
- Device ID, action performed, and success status
#### `set_device_level(device_id: str, level: int)`
Set device level (0-100) for dimmers.
**Parameters:**
- `device_id`: The device ID to control
- `level`: Brightness level (0-100)
**Returns:**
- Device ID, action performed, level set, and success status
## Example Usage with Claude Desktop
Add this to your Claude Desktop MCP configuration:
```json
{
"mcpServers": {
"lutron-caseta": {
"command": "uv",
"args": ["run", "--with", "lutron-caseta-mcp", "lutron-caseta-mcp"],
"env": {
"LUTRON_BRIDGE_IP": "192.168.1.100",
"LUTRON_CERT_DIR": "/path/to/certificates"
}
}
}
}
```
**Note:** If you encounter Python version errors, you may need to specify a Python version by adding `"--python", "3.12"` to the args array:
```json
{
"mcpServers": {
"lutron-caseta": {
"command": "uv",
"args": ["run", "--python", "3.12", "--with", "lutron-caseta-mcp", "lutron-caseta-mcp"],
"env": {
"LUTRON_BRIDGE_IP": "192.168.1.100",
"LUTRON_CERT_DIR": "/path/to/certificates"
}
}
}
}
```
Then you can ask Claude to:
- "Turn on the living room lights"
- "Set the bedroom lights to 50% brightness"
- "List all my lights"
- "Turn off all the lights in the kitchen"
## Troubleshooting
### Connection Issues
1. **Certificate files not found**: Run the pairing utility first
2. **Bridge connection failed**: Check that the bridge IP is correct and reachable
3. **Pairing timeout**: Make sure to press the bridge button within 30 seconds
### Common Error Messages
- `"Not connected to Lutron Caseta bridge"`: The server couldn't connect to your bridge. Check the IP address and certificate files.
- `"Certificate files not found"`: Run the pairing process first.
- `"Pairing failed"`: The bridge button wasn't pressed in time, or there was a network issue.
### Debug Mode
For more detailed logging, you can modify the server to enable debug mode or check the console output when running the server.
## Development
For development, clone the repository and install in development mode:
```bash
git clone https://github.com/dgalarza/lutron-caseta-mcp.git
cd lutron-caseta-mcp
uv sync
```
### Running Tests
```bash
uv run pytest
```
### Code Structure
- `src/lutron_caseta_mcp/server.py`: Main MCP server implementation
- `src/lutron_caseta_mcp/pairing.py`: Pairing utilities and standalone pairing tool
- `src/lutron_caseta_mcp/validation.py`: Input validation utilities
## Requirements
- `mcp>=1.0.0`: Model Context Protocol implementation
- `pylutron-caseta>=0.10.0`: Lutron Caseta bridge communication
## License
MIT License
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## Security Notes
- Certificate files contain sensitive authentication data
- Keep certificate files secure and don't commit them to version control
- The `.gitignore` file is configured to exclude certificate files
- Consider storing certificates in a secure location outside the project directory
Raw data
{
"_id": null,
"home_page": null,
"name": "lutron-caseta-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "caseta, home-automation, lutron, mcp, smart-home",
"author": null,
"author_email": "Damian Galarza <damian@damiangalarza.com>",
"download_url": "https://files.pythonhosted.org/packages/5b/f1/c3d29cfff5b6dc0d749fa90f3baac5a93b2df8cf08d2c6f8ed8e9e00f52a/lutron_caseta_mcp-0.1.0.tar.gz",
"platform": null,
"description": "# Lutron Caseta MCP Server\n\nA Model Context Protocol (MCP) server for controlling Lutron Caseta smart lights and devices. Powered by [pylutron-caseta](https://github.com/gurumitts/pylutron-caseta). This server allows AI assistants to interact with your Lutron Caseta bridge to control lights, check device status, and manage your smart home lighting.\n\n## Features\n\n- **Device Control**: Turn lights on/off and set dimmer levels\n- **Device Discovery**: List all lights and devices connected to your bridge\n- **Hybrid Pairing**: Support for both standalone pairing utility and MCP tool-based pairing\n- **Type Safety**: Full type hints for better development experience\n- **Error Handling**: Robust error handling with clear error messages\n\n## Prerequisites\n\n- Python 3.10 or higher\n- [uv](https://github.com/astral-sh/uv) package manager\n- Lutron Caseta bridge connected to your network\n- Network access to your Lutron Caseta bridge\n\nNo manual installation required - `uv` will handle everything automatically when you configure Claude Desktop.\n\n## Setup\n\n### 1. Find Your Bridge IP Address\n\nYou need to find the IP address of your Lutron Caseta bridge on your network. You can:\n- Check your router's device list\n- Use a network scanner app\n- Check the Lutron Caseta app settings\n\n### 2. Pair with Your Bridge\n\nYou have two options for pairing:\n\n#### Option A: MCP Tool Pairing (Recommended)\nStart the MCP server and use the `pair_bridge_tool` through Claude. Simply ask Claude to \"pair with my Lutron bridge at 192.168.1.100\" and Claude will guide you through the process.\n\n#### Option B: Standalone Pairing Utility\n```bash\n# Run the pairing utility\nuv run --with lutron-caseta-mcp lutron-caseta-pair 192.168.1.100\n\n# Or specify a custom directory for certificates\nuv run --with lutron-caseta-mcp lutron-caseta-pair 192.168.1.100 ./certificates\n```\n\n**For both options:**\n1. When prompted, press the small black button on the back of your Lutron Caseta bridge\n2. You have 30 seconds to press the button after the prompt appears\n3. Three certificate files will be created:\n - `caseta-bridge.crt` (CA certificate)\n - `caseta.crt` (Client certificate) \n - `caseta.key` (Private key)\n\n### 3. Configure Environment Variables\n\nSet the required environment variables:\n\n```bash\nexport LUTRON_BRIDGE_IP=192.168.1.100\nexport LUTRON_CERT_DIR=./certificates # Optional, defaults to current directory\n```\n\n## Usage\n\n### Available MCP Tools\n\nThe server provides the following tools that can be called by MCP clients:\n\n#### `pair_bridge_tool(host: str, output_dir: str = \".\")`\nPair with a Lutron Caseta bridge and save certificates.\n\n**Parameters:**\n- `host`: IP address of the bridge\n- `output_dir`: Directory to save certificate files (optional)\n\n**Returns:**\n- Success status, message, and certificate file paths\n\n#### `check_connection()`\nCheck connection status and certificate files.\n\n**Returns:**\n- Bridge IP, certificate directory, certificate status, and connection status\n\n#### `list_devices(domain: str = \"light\")`\nList all devices in the specified domain.\n\n**Parameters:**\n- `domain`: Device domain to list (default: \"light\")\n\n**Returns:**\n- List of devices with their IDs, names, and capabilities\n\n#### `turn_on_device(device_id: str)`\nTurn on a device by ID.\n\n**Parameters:**\n- `device_id`: The device ID to turn on\n\n**Returns:**\n- Device ID, action performed, and success status\n\n#### `turn_off_device(device_id: str)`\nTurn off a device by ID.\n\n**Parameters:**\n- `device_id`: The device ID to turn off\n\n**Returns:**\n- Device ID, action performed, and success status\n\n#### `set_device_level(device_id: str, level: int)`\nSet device level (0-100) for dimmers.\n\n**Parameters:**\n- `device_id`: The device ID to control\n- `level`: Brightness level (0-100)\n\n**Returns:**\n- Device ID, action performed, level set, and success status\n\n## Example Usage with Claude Desktop\n\nAdd this to your Claude Desktop MCP configuration:\n\n```json\n{\n \"mcpServers\": {\n \"lutron-caseta\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--with\", \"lutron-caseta-mcp\", \"lutron-caseta-mcp\"],\n \"env\": {\n \"LUTRON_BRIDGE_IP\": \"192.168.1.100\",\n \"LUTRON_CERT_DIR\": \"/path/to/certificates\"\n }\n }\n }\n}\n```\n\n**Note:** If you encounter Python version errors, you may need to specify a Python version by adding `\"--python\", \"3.12\"` to the args array:\n\n```json\n{\n \"mcpServers\": {\n \"lutron-caseta\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--python\", \"3.12\", \"--with\", \"lutron-caseta-mcp\", \"lutron-caseta-mcp\"],\n \"env\": {\n \"LUTRON_BRIDGE_IP\": \"192.168.1.100\",\n \"LUTRON_CERT_DIR\": \"/path/to/certificates\"\n }\n }\n }\n}\n```\n\nThen you can ask Claude to:\n- \"Turn on the living room lights\"\n- \"Set the bedroom lights to 50% brightness\"\n- \"List all my lights\"\n- \"Turn off all the lights in the kitchen\"\n\n## Troubleshooting\n\n### Connection Issues\n\n1. **Certificate files not found**: Run the pairing utility first\n2. **Bridge connection failed**: Check that the bridge IP is correct and reachable\n3. **Pairing timeout**: Make sure to press the bridge button within 30 seconds\n\n### Common Error Messages\n\n- `\"Not connected to Lutron Caseta bridge\"`: The server couldn't connect to your bridge. Check the IP address and certificate files.\n- `\"Certificate files not found\"`: Run the pairing process first.\n- `\"Pairing failed\"`: The bridge button wasn't pressed in time, or there was a network issue.\n\n### Debug Mode\n\nFor more detailed logging, you can modify the server to enable debug mode or check the console output when running the server.\n\n## Development\n\nFor development, clone the repository and install in development mode:\n\n```bash\ngit clone https://github.com/dgalarza/lutron-caseta-mcp.git\ncd lutron-caseta-mcp\nuv sync\n```\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n### Code Structure\n\n- `src/lutron_caseta_mcp/server.py`: Main MCP server implementation\n- `src/lutron_caseta_mcp/pairing.py`: Pairing utilities and standalone pairing tool\n- `src/lutron_caseta_mcp/validation.py`: Input validation utilities\n\n## Requirements\n\n- `mcp>=1.0.0`: Model Context Protocol implementation\n- `pylutron-caseta>=0.10.0`: Lutron Caseta bridge communication\n\n## License\n\nMIT License\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Security Notes\n\n- Certificate files contain sensitive authentication data\n- Keep certificate files secure and don't commit them to version control\n- The `.gitignore` file is configured to exclude certificate files\n- Consider storing certificates in a secure location outside the project directory",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for controlling Lutron Caseta lights",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"caseta",
" home-automation",
" lutron",
" mcp",
" smart-home"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "507c64dbe72eb16bb3f5e5a0918d9c447b0252a85eb51f5717021ac6eb07f8c1",
"md5": "5f5c23d589e4215c21c436be9c44ac11",
"sha256": "cb18657d37290ad92b9f42bfb7e8c68abe0615b4128d5e2cdff290d98c418db2"
},
"downloads": -1,
"filename": "lutron_caseta_mcp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f5c23d589e4215c21c436be9c44ac11",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12169,
"upload_time": "2025-07-17T22:15:48",
"upload_time_iso_8601": "2025-07-17T22:15:48.511452Z",
"url": "https://files.pythonhosted.org/packages/50/7c/64dbe72eb16bb3f5e5a0918d9c447b0252a85eb51f5717021ac6eb07f8c1/lutron_caseta_mcp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5bf1c3d29cfff5b6dc0d749fa90f3baac5a93b2df8cf08d2c6f8ed8e9e00f52a",
"md5": "05057439c55868ba0e2cc13ede865058",
"sha256": "db7b0c6e6338698d7931413105c4c2f9b3a33271344f87bd5fea5b1b03a37528"
},
"downloads": -1,
"filename": "lutron_caseta_mcp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "05057439c55868ba0e2cc13ede865058",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 83823,
"upload_time": "2025-07-17T22:15:49",
"upload_time_iso_8601": "2025-07-17T22:15:49.533367Z",
"url": "https://files.pythonhosted.org/packages/5b/f1/c3d29cfff5b6dc0d749fa90f3baac5a93b2df8cf08d2c6f8ed8e9e00f52a/lutron_caseta_mcp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 22:15:49",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "lutron-caseta-mcp"
}
JSON