CLAUDE_SETUP.mdā¢6.38 kB
# Claude Desktop Configuration for SmartThings MCP Server
This guide shows you how to configure Claude Desktop to use your SmartThings MCP server.
## Prerequisites
1. **Build the Docker image** (if not already built):
```bash
cd /Users/username/GitHub/smartthings_mcp
make build
# or
docker build -t smartthings-mcp:py .
```
2. **Get your SmartThings Personal Access Token (PAT)**:
- Visit https://account.smartthings.com/tokens
- Click "Generate new token"
- Select scopes: `devices` (read/execute), `locations` (read)
- Copy the token
3. **Find your Location ID** (optional but recommended):
```bash
export SMARTTHINGS_PAT="your_token_here"
docker run --rm -i -e SMARTTHINGS_PAT smartthings-mcp:py
# Then call list_locations() to get your location ID
```
## Configuration
### Option 1: Docker-based Configuration (Recommended)
Add this to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"smartthings": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--env",
"SMARTTHINGS_PAT",
"--env",
"SMARTTHINGS_LOCATION_ID",
"smartthings-mcp:py"
],
"env": {
"SMARTTHINGS_PAT": "YOUR_SMARTTHINGS_PAT_TOKEN_HERE",
"SMARTTHINGS_LOCATION_ID": "your-location-id-optional"
}
}
}
}
```
### Option 2: Python Virtual Environment (Alternative)
If you prefer to run without Docker:
1. **Create and activate a virtual environment**:
```bash
cd /Users/username/GitHub/smartthings_mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
2. **Add to Claude Desktop config**:
```json
{
"mcpServers": {
"smartthings": {
"command": "/Users/username/GitHub/smartthings_mcp/venv/bin/python",
"args": [
"-m",
"app.main"
],
"cwd": "/Users/username/GitHub/smartthings_mcp",
"env": {
"SMARTTHINGS_PAT": "YOUR_SMARTTHINGS_PAT_TOKEN_HERE",
"SMARTTHINGS_LOCATION_ID": "your-location-id-optional"
}
}
}
}
```
## Setup Steps
1. **Replace the placeholder values**:
- Replace `YOUR_SMARTTHINGS_PAT_TOKEN_HERE` with your actual PAT token
- Replace `your-location-id-optional` with your location ID (or remove this line)
2. **Save the configuration file**
3. **Restart Claude Desktop** completely (quit and reopen)
4. **Verify the connection**:
- Open Claude Desktop
- Look for the š icon in the bottom right
- Click it to see available MCP servers
- You should see "smartthings" listed with available tools
## Available Tools
Once connected, you can ask Claude to:
- **List locations**: "Show me my SmartThings locations"
- **List devices**: "What SmartThings devices do I have?"
- **Get device status**: "What's the status of my living room light?"
- **Control switches**: "Turn on the kitchen light"
- **Check fridge**: "What's the temperature in my refrigerator?"
- **Device health**: "Is my smart plug online?"
## Example Prompts
```
"List all my SmartThings devices"
"Turn on the living room light"
"What's the status of my refrigerator?"
"Show me all devices in location [location-id]"
"Turn off all lights" (Claude will use the tools to find and control lights)
```
## Troubleshooting
### MCP server not showing up
- Check that Docker image is built: `docker images | grep smartthings-mcp`
- Verify the config file is valid JSON (use a JSON validator)
- Check Claude Desktop logs (usually in the same directory as config)
### "SMARTTHINGS_PAT is required" error
- Make sure you replaced the placeholder with your actual token
- Verify the token has the correct scopes
### Connection timeout
- Ensure Docker is running
- Check that the image can start: `docker run --rm -i -e SMARTTHINGS_PAT=test smartthings-mcp:py`
### Tools not working
- Verify your PAT has the correct permissions
- Check that you have devices in your SmartThings account
- Use `list_locations()` and `list_devices()` first to see what's available
## Security Notes
- Your PAT token is stored in the Claude Desktop config file
- On macOS/Linux, ensure the config file has proper permissions:
```bash
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
- Never commit your config file with real tokens to version control
- Tokens can be revoked at https://account.smartthings.com/tokens
## Advanced Configuration
### Using environment variables (more secure)
Instead of putting the token directly in the config:
1. **Set environment variable** in your shell profile (`~/.zshrc` or `~/.bashrc`):
```bash
export SMARTTHINGS_PAT="your_token_here"
export SMARTTHINGS_LOCATION_ID="your_location_id"
```
2. **Update config** to use the environment variables:
```json
{
"mcpServers": {
"smartthings": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--env",
"SMARTTHINGS_PAT",
"--env",
"SMARTTHINGS_LOCATION_ID",
"smartthings-mcp:py"
]
}
}
}
```
Note: Remove the `"env"` section entirely - Docker will inherit from your shell.
3. **Restart your terminal and Claude Desktop**
### Multiple SmartThings Accounts
You can configure multiple accounts by giving each a unique name:
```json
{
"mcpServers": {
"smartthings-home": {
"command": "docker",
"args": ["run", "--rm", "-i", "--env", "SMARTTHINGS_PAT", "smartthings-mcp:py"],
"env": {
"SMARTTHINGS_PAT": "home_account_token"
}
},
"smartthings-office": {
"command": "docker",
"args": ["run", "--rm", "-i", "--env", "SMARTTHINGS_PAT", "smartthings-mcp:py"],
"env": {
"SMARTTHINGS_PAT": "office_account_token"
}
}
}
}
```
## Getting Help
If you encounter issues:
1. Check the Docker logs: `docker logs [container-id]`
2. Test the server manually: `make run`
3. Verify your token at https://account.smartthings.com/tokens
4. Review the README.md for detailed tool documentation