Labsco
technohead logo

SmartThingsMCP

from technohead

A comprehensive FastMCP 2.0 server and client for interacting with SmartThings devices, locations, rooms, modes, scenes, and automation rules through the SmartThings API.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#git#maps

SmartThingsMCP Server and Client

A comprehensive FastMCP 2.0 server and client for interacting with SmartThings devices, locations, rooms, modes, scenes, and automation rules through the SmartThings API.

Overview

SmartThingsMCP provides:

  • FastMCP 2.0 Server: Exposes SmartThings API functionality as MCP tools
  • Smart Client: Python client with intelligent caching, async support, and multiple transport options
  • Modular Architecture: Organized by functionality (devices, locations, rooms, modes, scenes, rules)
  • Two-Level Caching: Both client and server-side caching for optimal performance
  • Multiple Transports: HTTP, SSE (Server-Sent Events), and STDIO support
  • OAuth 2.0 Authentication: Secure token-based authentication with SmartThings API

Components

Server

  • SmartThingsMCPServer.py: FastMCP 2.0 server exposing SmartThings API as MCP tools
  • modules/server/: Server tool implementations
    • devices.py: Device management tools (list, get, update, delete, execute commands, etc.)
    • locations.py: Location management tools (create, read, update, delete locations and rooms)
    • rooms.py: Room management tools (list, create, update, delete rooms)
    • modes.py: Mode management tools (list, get, set location modes)
    • scenes.py: Scene management tools (list, get, execute, create, update, delete scenes)
    • rules.py: Automation rule tools (list, get, create, update, delete, execute rules)
    • structure_tools.py: Structure generation tools for LLM integration
    • common.py: Shared utilities for API requests, URL building, and parameter filtering

Client

  • SmartThingsMCPClient.py: CLI for interacting with the MCP server
  • modules/client/: Client implementation
    • main.py: Main SmartThingsMCPClient class combining all mixins
    • base.py: BaseClient with transport handling and tool invocation
    • cache.py: CacheMixin with LRU caching, TTL management, and cache statistics
    • devices.py: DevicesMixin with device operation methods
    • locations.py: LocationsMixin with location and room methods
    • rooms.py: RoomsMixin with room-specific methods
    • modes.py: ModesMixin with mode management methods
    • rules.py: RulesMixin with rule management methods
    • scenes.py: ScenesMixin with scene management methods
    • utils.py: Utility functions for tool conversion and action execution
    • utils_ext.py: Extended utilities (note: currently unused)

API Endpoints

SmartThingsMCP exposes the following API endpoints as MCP tools:

Device Management

  • list_devices: Get a list of all devices (supports filtering by capability, location, room, or device ID)
  • get_device: Get details of a specific device
  • update_device: Update a device's label
  • delete_device: Delete a device
  • execute_command: Execute a command on a device component
  • get_device_status: Get the current status of a device
  • get_device_components: Get all components of a device
  • get_device_capabilities: Get capabilities of a device component
  • get_device_health: Get the health/connectivity status of a device
  • get_device_presentation: Get the UI presentation details of a device

Location Management

  • list_locations: Get a list of all locations
  • get_location: Get details of a specific location
  • create_location: Create a new location with coordinates and address information
  • update_location: Update location details (name, coordinates, address)
  • delete_location: Delete a location
  • get_location_rooms: Get all rooms in a location (convenience method)

Room Management

  • list_rooms: Get all rooms in a location
  • get_room: Get details of a specific room
  • create_room: Create a new room in a location
  • update_room: Update a room's name
  • delete_room: Delete a room from a location

Mode Management

  • list_modes: Get all available modes for a location
  • get_mode: Get details of a specific mode
  • get_current_mode: Get the currently active mode for a location
  • set_mode: Change the current mode for a location

Scene Management

  • list_scenes: Get all scenes (optionally filtered by location)
  • get_scene: Get details of a specific scene
  • execute_scene: Execute/run a scene
  • create_scene: Create a new scene with actions and visual properties
  • update_scene: Update an existing scene (name, icon, colors, actions)
  • delete_scene: Delete a scene

Rule Management

  • list_rules: Get all automation rules (optionally filtered by location)
  • get_rule: Get details of a specific rule
  • create_rule: Create a new automation rule with conditions and actions
  • update_rule: Update an existing rule (name, triggers, actions, enabled state)
  • delete_rule: Delete an automation rule
  • execute_rule: Manually trigger execution of a rule

Features

Intelligent Caching

Both the SmartThingsMCPClient and SmartThingsMCPServer include comprehensive caching to improve performance:

Client-Side Caching

The SmartThingsMCPClient provides:

  • Automatic caching of read-only operations (list_devices, list_locations, etc.)
  • TTL-based expiration (default: 5 minutes, configurable)
  • Smart cache invalidation on write operations (execute_command, update_device, etc.)
  • LRU eviction when cache is full
  • Cache statistics tracking (hits, misses, hit rate)
  • Green visual feedback: ✓ Cache hit: list_locations

See CACHING.md for detailed documentation.

Server-Side Caching

The SmartThingsMCPServer provides:

  • Automatic caching of all GET requests to SmartThings API
  • TTL-based expiration (default: 5 minutes)
  • Full cache invalidation on write operations (POST, PUT, DELETE)
  • LRU eviction when cache is full
  • Cache statistics tracking
  • Green visual feedback: ✓ Server cache hit: GET devices

See SERVER_CACHING.md for detailed documentation.

Two-Level Caching: When both client and server caching are active, you get maximum performance with two layers of caching!

Performance Benefits:

  • 60-80% reduction in API calls
  • 5-10x faster response times for cached data
  • Lower rate limit usage

Rule Management

The server provides comprehensive rule management capabilities:

  • list_rules: List all automation rules for a location
  • get_rule: Get details of a specific rule
  • create_rule: Create a new automation rule with conditions and actions
  • update_rule: Update an existing rule (name, triggers, actions, or enabled state)
  • delete_rule: Delete a rule
  • execute_rule: Manually execute a rule

Enable/Disable Rules:

Copy & paste — that's it
# Disable a rule
client.update_rule(auth=token, rule_id="abc-123", enabled=False)

# Enable a rule
client.update_rule(auth=token, rule_id="abc-123", enabled=True)

The enabled parameter was added in December 2025 to support toggling rule state without deleting the rule.

Authentication

SmartThingsMCP uses OAuth 2.0 bearer tokens for authentication with the SmartThings API.

Token Requirements

  • Must be a valid SmartThings API token (OAuth 2.0 bearer token)
  • Token must have appropriate scopes for the operations you want to perform
  • Token never expires when obtained from the SmartThings Developer Portal
  • Keep your token secure and never commit it to version control

Common Authentication Issues

401 Unauthorized:

Copy & paste — that's it
Error calling tool list_devices: 401 Unauthorized
  • Verify the token is valid and not expired
  • Check that the token has been generated from SmartThings Developer Portal
  • Ensure you're passing the token with the --auth flag

403 Forbidden:

Copy & paste — that's it
Error calling tool list_devices: 403 Forbidden
  • The token exists but lacks required scopes
  • Some features (like Rules) require an Enterprise SmartThings account
  • Grant additional scopes to the token in SmartThings Developer Portal

Scopes Required by Feature

FeatureRequired Scopes
List/Get Devicesr:devices:*
Control Devicesw:devices:*
List/Get Locationsr:locations:*
Create/Update/Delete Locationsw:locations:*
List/Get Scenesr:scenes:*
Execute Scenesx:scenes:*
Create/Update/Delete Scenesw:scenes:*
List/Get Rulesr:rules:*
Create/Update/Delete Rulesw:rules:*
List/Get/Set Modesr:locations:*

Example Scripts

Monitor Device Status

Copy & paste — that's it
import asyncio
from modules.client.main import SmartThingsMCPClient

async def monitor_devices(token):
    client = SmartThingsMCPClient(auth_token=token)
    
    # Get all devices
    devices = await client.list_devices(auth=token)
    
    for device in devices['items']:
        try:
            status = await client.get_device_status(
                auth=token,
                device_id=device['deviceId']
            )
            print(f"{device['label']}: {status}")
        except Exception as e:
            print(f"Error getting status for {device['label']}: {e}")

asyncio.run(monitor_devices("YOUR_TOKEN"))

Control Multiple Devices

Copy & paste — that's it
import asyncio
from modules.client.main import SmartThingsMCPClient

async def control_devices(token, device_ids, command):
    client = SmartThingsMCPClient(auth_token=token)
    
    for device_id in device_ids:
        try:
            result = await client.execute_command(
                auth=token,
                device_id=device_id,
                component="main",
                capability="switch",
                command=command
            )
            print(f"Device {device_id}: {result}")
        except Exception as e:
            print(f"Error controlling {device_id}: {e}")

asyncio.run(control_devices("YOUR_TOKEN", ["device1", "device2"], "on"))

Scene Execution

Copy & paste — that's it
import asyncio
from modules.client.main import SmartThingsMCPClient

async def execute_morning_routine(token):
    client = SmartThingsMCPClient(auth_token=token)
    
    # Get morning scene
    scenes = await client.list_scenes(auth=token)
    morning_scene = next(
        (s for s in scenes['items'] if 'morning' in s.get('sceneName', '').lower()),
        None
    )
    
    if morning_scene:
        result = await client.execute_scene(
            auth=token,
            scene_id=morning_scene['sceneId']
        )
        print(f"Executed scene: {result}")

asyncio.run(execute_morning_routine("YOUR_TOKEN"))

Environment Variables

You can optionally use environment variables for common settings:

Copy & paste — that's it
export SMARTTHINGS_TOKEN="your-token-here"
export MCP_SERVER_HOST="localhost"
export MCP_SERVER_PORT="8000"
export MCP_TRANSPORT="http"

API Reference

Complete API reference is available through the MCP tools system. List all available tools:

Copy & paste — that's it
python SmartThingsMCPClient.py --action list_tools --pretty

This will display all available tools with their parameters and descriptions.

Contributing

When extending SmartThingsMCP:

  1. Follow the existing module structure
  2. Add tools to appropriate module (devices.py, locations.py, etc.)
  3. Include proper docstrings with parameter and return descriptions
  4. Test with the client
  5. Update README.md with new tool documentation

License

See LICENSE file for license information.