SmartThings MCP Server (Python)

A production-ready, Dockerized MCP (Model Context Protocol) server for controlling and querying SmartThings devices via Personal Access Token (PAT).

Features

✅ Fully Async: Efficient async/await implementation with proper resource management
✅ Comprehensive Logging: Detailed logging for debugging and monitoring
✅ Type Safety: Full type hints and Pydantic validation
✅ Error Handling: Structured error handling with meaningful messages
✅ Optimized API Calls: Direct device lookups to minimize API requests
✅ Docker Best Practices: Non-root user, health checks, minimal image size
✅ Resource Cleanup: Proper HTTP client lifecycle management

Project Structure

.
├── Dockerfile              # Production-ready Docker image
├── docker-compose.yml      # Docker Compose configuration
├── .dockerignore          # Docker build exclusions
├── .env.example           # Environment variable template
├── requirements.txt       # Python dependencies
├── app/
│   ├── __init__.py
│   ├── main.py           # MCP server and tool definitions
│   └── smartthings.py    # SmartThings API client
└── README.md             # This file

Setup

1. Get a SmartThings Personal Access Token (PAT)

Visit https://account.smartthings.com/tokens
Click "Generate new token"
Give it a name (e.g., "MCP Server")
Select required scopes:
- devices (read and execute)
- locations (read)
Copy the generated token

2. Configure Environment

cp .env.example .env
# Edit .env and add your SMARTTHINGS_PAT

3. Build and Run

Using Docker

# Build the image
docker build -t smartthings_mcp:latest .

# Run with stdio transport
docker run --rm -i \
  -e SMARTTHINGS_PAT=$SMARTTHINGS_PAT \
  -e SMARTTHINGS_LOCATION_ID=$SMARTTHINGS_LOCATION_ID \
  smartthings_mcp:latest

Using Docker Compose

# Build and run
docker compose build
docker compose run --rm smartthings-mcp python -m app.main

Local Development

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export SMARTTHINGS_PAT="your_pat_here"

# Run the server
python -m app.main

Available Tools

`list_locations()`

List all SmartThings locations accessible with the current PAT.

Returns: List of location objects with locationId, name, and metadata.

`list_rooms(locationId?)`

List all rooms in a SmartThings location.

Parameters:

locationId (optional): The location ID. Falls back to SMARTTHINGS_LOCATION_ID env var or first available location.

Returns: List of room objects with roomId, name, and metadata.

`list_devices(locationId?, roomId?)`

List all SmartThings devices, optionally filtered by location and/or room.

Parameters:

locationId (optional): Filter devices by location
roomId (optional): Filter devices by room

Returns: List of device objects with deviceId, label, capabilities, and metadata.

`device_status({ deviceId?, name? })`

Get the current status of a SmartThings device.

Parameters:

deviceId (optional): The unique device ID (preferred for efficiency)
name (optional): Device name/label to search for (slower, searches all devices)

Returns: Device information with current status and flattened summary.

Note: Provide at least one of deviceId or name.

`switch_device({ deviceId?, name?, command, component? })`

Turn a SmartThings switch device on or off.

Parameters:

deviceId (optional): The unique device ID (preferred)
name (optional): Device name/label to search for
command (required): Either "on" or "off"
component (optional): Device component (default: "main")

Returns: Device information and command execution result.

`fridge_status({ deviceId?, name? })`

Get detailed status of a SmartThings refrigerator/fridge device.

Parameters:

deviceId (optional): The unique device ID
name (optional): Device name/label to search for

Returns: Refrigerator-specific status summary including:

Power state
Refrigerator and freezer temperatures
Door open/closed state
Ice maker status
Defrost mode
All temperature, door, ice, humidity, and energy-related attributes

Note: If neither parameter is provided, automatically searches for devices with "fridge" or "refrigerator" in the name.

`device_health(deviceId)`

Get the health status of a SmartThings device.

Parameters:

deviceId (required): The unique device ID

Returns: Device health information including online/offline state.

Architecture Improvements

Async Design

All tools are fully async for better concurrency
Uses a single HTTP client with connection pooling
Proper cleanup on shutdown via lifespan handler

Error Handling

Pydantic validation for all inputs
Structured error messages
Graceful fallbacks (e.g., health check returns "unknown" instead of failing)

Performance Optimizations

Direct device GET endpoint when using deviceId (avoids listing all devices)
Efficient device search with early exit
Connection reuse across all requests

Security

Runs as non-root user in Docker
Minimal attack surface (no exposed ports)
Token never logged

Logging

Comprehensive logging at INFO and DEBUG levels
Structured log format with timestamps
Request/response logging for debugging

Environment Variables

Variable	Required	Default	Description
`SMARTTHINGS_PAT`	✅ Yes	-	SmartThings Personal Access Token
`SMARTTHINGS_LOCATION_ID`	❌ No	-	Default location ID for room queries
`SMARTTHINGS_BASE_URL`	❌ No	`https://api.smartthings.com/v1`	SmartThings API base URL
`MCP_TRANSPORT`	❌ No	`stdio`	MCP transport method

Development

Running Tests

# Install dev dependencies
pip install pytest pytest-asyncio httpx

# Run tests
pytest

Logging Levels

Set the log level via environment:

# Debug level (verbose)
export LOG_LEVEL=DEBUG

# Info level (default)
export LOG_LEVEL=INFO

# Warning level (quiet)
export LOG_LEVEL=WARNING

Code Style

This project follows:

PEP 8 style guide
Type hints for all functions
Docstrings for all public APIs

Troubleshooting

"SMARTTHINGS_PAT is required"

Ensure you've set the SMARTTHINGS_PAT environment variable
Check that your PAT has the correct scopes

"No locations found"

Verify your PAT has locations:read scope
Check that you have at least one location in your SmartThings account

"Device not found"

Use list_devices() to see available devices
Ensure the device name or ID is correct (case-insensitive for names)
Check that the device is in the specified location/room if filters are applied

HTTP Timeout Errors

Increase timeout in smartthings.py (default: 15s)
Check network connectivity to SmartThings API

License

MIT License - feel free to use and modify as needed.

Contributing

Contributions welcome! Please:

Add tests for new features
Update documentation
Follow existing code style
Ensure all tests pass

Changelog

v2.0.0 (Current)

✅ Full async/await implementation
✅ Comprehensive logging and error handling
✅ Optimized API calls with direct device lookups
✅ Docker best practices (non-root user, health checks)
✅ Pydantic validation for all inputs
✅ Proper resource cleanup
✅ Complete type hints and docstrings

v1.0.0 (Original)

Basic MCP server implementation
Synchronous tool functions
Basic error handling

SmartThings MCP Server (Python)

A production-ready, Dockerized MCP (Model Context Protocol) server for controlling and querying SmartThings devices via Personal Access Token (PAT).

Features

✅ Fully Async: Efficient async/await implementation with proper resource management
✅ Comprehensive Logging: Detailed logging for debugging and monitoring
✅ Type Safety: Full type hints and Pydantic validation
✅ Error Handling: Structured error handling with meaningful messages
✅ Optimized API Calls: Direct device lookups to minimize API requests
✅ Docker Best Practices: Non-root user, health checks, minimal image size
✅ Resource Cleanup: Proper HTTP client lifecycle management

Project Structure

.
├── Dockerfile              # Production-ready Docker image
├── docker-compose.yml      # Docker Compose configuration
├── .dockerignore          # Docker build exclusions
├── .env.example           # Environment variable template
├── requirements.txt       # Python dependencies
├── app/
│   ├── __init__.py
│   ├── main.py           # MCP server and tool definitions
│   └── smartthings.py    # SmartThings API client
└── README.md             # This file

Setup

1. Get a SmartThings Personal Access Token (PAT)

Visit https://account.smartthings.com/tokens
Click "Generate new token"
Give it a name (e.g., "MCP Server")
Select required scopes:
- devices (read and execute)
- locations (read)
Copy the generated token

2. Configure Environment

cp .env.example .env
# Edit .env and add your SMARTTHINGS_PAT

3. Build and Run

Using Docker

# Build the image
docker build -t smartthings_mcp:latest .

# Run with stdio transport
docker run --rm -i \
  -e SMARTTHINGS_PAT=$SMARTTHINGS_PAT \
  -e SMARTTHINGS_LOCATION_ID=$SMARTTHINGS_LOCATION_ID \
  smartthings_mcp:latest

Using Docker Compose

# Build and run
docker compose build
docker compose run --rm smartthings-mcp python -m app.main

Local Development

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export SMARTTHINGS_PAT="your_pat_here"

# Run the server
python -m app.main

Available Tools

`list_locations()`

List all SmartThings locations accessible with the current PAT.

Returns: List of location objects with locationId, name, and metadata.

`list_rooms(locationId?)`

List all rooms in a SmartThings location.

Parameters:

locationId (optional): The location ID. Falls back to SMARTTHINGS_LOCATION_ID env var or first available location.

Returns: List of room objects with roomId, name, and metadata.

`list_devices(locationId?, roomId?)`

List all SmartThings devices, optionally filtered by location and/or room.

Parameters:

locationId (optional): Filter devices by location
roomId (optional): Filter devices by room

Returns: List of device objects with deviceId, label, capabilities, and metadata.

`device_status({ deviceId?, name? })`

Get the current status of a SmartThings device.

Parameters:

deviceId (optional): The unique device ID (preferred for efficiency)
name (optional): Device name/label to search for (slower, searches all devices)

Returns: Device information with current status and flattened summary.

Note: Provide at least one of deviceId or name.

`switch_device({ deviceId?, name?, command, component? })`

Turn a SmartThings switch device on or off.

Parameters:

deviceId (optional): The unique device ID (preferred)
name (optional): Device name/label to search for
command (required): Either "on" or "off"
component (optional): Device component (default: "main")

Returns: Device information and command execution result.

`fridge_status({ deviceId?, name? })`

Get detailed status of a SmartThings refrigerator/fridge device.

Parameters:

deviceId (optional): The unique device ID
name (optional): Device name/label to search for

Returns: Refrigerator-specific status summary including:

Power state
Refrigerator and freezer temperatures
Door open/closed state
Ice maker status
Defrost mode
All temperature, door, ice, humidity, and energy-related attributes

Note: If neither parameter is provided, automatically searches for devices with "fridge" or "refrigerator" in the name.

`device_health(deviceId)`

Get the health status of a SmartThings device.

Parameters:

deviceId (required): The unique device ID

Returns: Device health information including online/offline state.

Architecture Improvements

Async Design

All tools are fully async for better concurrency
Uses a single HTTP client with connection pooling
Proper cleanup on shutdown via lifespan handler

Error Handling

Pydantic validation for all inputs
Structured error messages
Graceful fallbacks (e.g., health check returns "unknown" instead of failing)

Performance Optimizations

Direct device GET endpoint when using deviceId (avoids listing all devices)
Efficient device search with early exit
Connection reuse across all requests

Security

Runs as non-root user in Docker
Minimal attack surface (no exposed ports)
Token never logged

Logging

Comprehensive logging at INFO and DEBUG levels
Structured log format with timestamps
Request/response logging for debugging

Environment Variables

Variable	Required	Default	Description
`SMARTTHINGS_PAT`	✅ Yes	-	SmartThings Personal Access Token
`SMARTTHINGS_LOCATION_ID`	❌ No	-	Default location ID for room queries
`SMARTTHINGS_BASE_URL`	❌ No	`https://api.smartthings.com/v1`	SmartThings API base URL
`MCP_TRANSPORT`	❌ No	`stdio`	MCP transport method

Development

Running Tests

# Install dev dependencies
pip install pytest pytest-asyncio httpx

# Run tests
pytest

Logging Levels

Set the log level via environment:

# Debug level (verbose)
export LOG_LEVEL=DEBUG

# Info level (default)
export LOG_LEVEL=INFO

# Warning level (quiet)
export LOG_LEVEL=WARNING

Code Style

This project follows:

PEP 8 style guide
Type hints for all functions
Docstrings for all public APIs

Troubleshooting

"SMARTTHINGS_PAT is required"

Ensure you've set the SMARTTHINGS_PAT environment variable
Check that your PAT has the correct scopes

"No locations found"

Verify your PAT has locations:read scope
Check that you have at least one location in your SmartThings account

"Device not found"

Use list_devices() to see available devices
Ensure the device name or ID is correct (case-insensitive for names)
Check that the device is in the specified location/room if filters are applied

HTTP Timeout Errors

Increase timeout in smartthings.py (default: 15s)
Check network connectivity to SmartThings API

License

MIT License - feel free to use and modify as needed.

Contributing

Contributions welcome! Please:

Add tests for new features
Update documentation
Follow existing code style
Ensure all tests pass

Changelog

v2.0.0 (Current)

✅ Full async/await implementation
✅ Comprehensive logging and error handling
✅ Optimized API calls with direct device lookups
✅ Docker best practices (non-root user, health checks)
✅ Pydantic validation for all inputs
✅ Proper resource cleanup
✅ Complete type hints and docstrings

v1.0.0 (Original)

Basic MCP server implementation
Synchronous tool functions
Basic error handling