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:

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

Installation

Prerequisites

• Python 3.8 or higher

• pip or another Python package manager

Setup

1. Install dependencies:

Required packages:

• fastmcp>=2.0.0: FastMCP 2.0 framework for MCP server/client

• requests>=2.28.0: HTTP library for SmartThings API calls

2. Obtain a SmartThings API Token:

   • Visit SmartThings Developer Portal

   • Create a new API token with the following scopes:

     • r:devices:* (read devices)

     • w:devices:* (control devices)

     • r:locations:* (read locations)

     • w:locations:* (create/update locations)

     • r:rules:* (read rules, requires Enterprise account)

     • w:rules:* (write rules, requires Enterprise account)

     • r:scenes:* (read scenes)

     • x:scenes:* (execute scenes)

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:

• 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:

• 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

Getting Started

Starting the Server

1. Start the SmartThingsMCP server:

Using the Command-Line Client

The SmartThingsMCPClient.py provides a CLI interface:

Client Options

Using Python Client Programmatically

Troubleshooting

Transport Configuration

SmartThingsMCP supports three transport mechanisms for client-server communication:

HTTP Transport (Recommended for most use cases)

• Default port: 8000

• URL pattern: http://localhost:8000/mcp

• Best for: External integrations, LLM tools, web services

• Advantages:

  • Simple HTTP/REST interface

  • Easy to debug with standard tools

  • Compatible with most firewalls

  • Stateless connections

SSE Transport (Server-Sent Events)

• Default port: 8000

• URL pattern: http://localhost:8000/sse

• Best for: Real-time updates, event streaming, server push

• Advantages:

  • Bidirectional communication

  • Event-driven architecture

  • Lower latency for updates

STDIO Transport (Direct integration)

• No network overhead

• Best for: Direct Python integration, embedded systems

• Advantages:

  • No port/network configuration needed

  • Direct process communication

  • Lowest latency

Client Configuration

Cache Configuration

The SmartThingsMCPClient includes intelligent caching with full control:

Cacheable Operations (automatic caching):

• list_devices

• get_device

• list_locations

• get_location

• list_rooms

• get_room

• list_modes

• get_mode

• get_current_mode

• list_scenes

• get_scene

• list_rules

• get_rule

Cache-Invalidating Operations (automatic cache clearing):

• update_device

• delete_device

• execute_command

• create_location

• update_location

• delete_location

• create_room

• update_room

• delete_room

• set_mode

• create_scene

• update_scene

• delete_scene

• create_rule

• update_rule

• delete_rule

• execute_rule

• execute_scene

Logging

SmartThingsMCP uses Python's standard logging module:

Log levels:

• DEBUG: Detailed diagnostic information

• INFO: General informational messages (default)

• WARNING: Warning messages

• ERROR: Error messages

• CRITICAL: Critical errors

Common Errors and Solutions

Common Errors and Solutions

Connection Errors

Error:

Causes and solutions:

• Server is not running: Start the server with python SmartThingsMCPServer.py

• Wrong transport type: Ensure client and server use same transport (http, sse, or stdio)

• Wrong port: Verify port matches between client and server

• Wrong host: Check hostname/IP address is correct

• Network/firewall: Ensure port is open and accessible

Debugging:

Authentication Errors

Error:

Solutions:

• Provide auth token with --auth YOUR_TOKEN flag

• Ensure token is valid: verify in SmartThings Developer Portal

• Check token has not expired

• Verify token has required scopes

Example:

Error:

Solutions:

• Token is invalid or expired

• Token format is incorrect (must be OAuth 2.0 bearer token)

• Generate new token from SmartThings Developer Portal

Error:

Solutions:

• Token lacks required scopes for the operation

• SmartThings account doesn't have access to feature (e.g., Rules API requires Enterprise)

• Grant additional scopes in SmartThings Developer Portal

API Response Errors

Error:

Solutions:

• Device ID doesn't exist

• Device has been deleted

• List devices first to get valid IDs: list_devices action

Error:

Solutions:

• Check valid components: Use get_device_components to list available components

• Check valid capabilities: Use get_device_capabilities with correct component_id

• Device doesn't support the command you're trying to execute

Rate Limiting

Error:

Solutions:

• SmartThings API rate limit exceeded

• Enable caching to reduce API calls (enabled by default)

• Increase cache TTL to keep data longer

• Implement request throttling in your code

Check cache effectiveness:

Cache Issues

Problem: Stale data in cache

Solutions:

• Reduce cache TTL: cache_ttl=60 (1 minute)

• Manually clear cache: client.clear_cache()

• Disable cache if data must be real-time: enable_cache=False

Problem: Cache causing high memory usage

Solutions:

• Reduce max cache size: max_cache_size=100

• Reduce cache TTL to expire entries sooner

• Periodically clear cache: client.clear_cache()

Advanced Usage

Custom Tool Implementation

You can extend SmartThingsMCP with custom tools by modifying the server modules:

Integration with LLMs

SmartThingsMCP tools are designed to work with Language Models:

Error Handling

Performance Optimization

1. Enable caching (default: enabled):

   # Already enabled by default client = SmartThingsMCPClient(enable_cache=True)

2. Adjust cache TTL for your use case:

   # More frequent updates needed client = SmartThingsMCPClient(cache_ttl=60) # 1 minute # Stable data, longer TTL client = SmartThingsMCPClient(cache_ttl=900) # 15 minutes

3. Use appropriate transport:

   • HTTP: Best for most scenarios

   • STDIO: Best latency for local integration

   • SSE: Best for real-time updates

4. Batch operations:

   # Get all data at once rather than in loops devices = await client.list_devices(auth=token) for device in devices['items']: # Use data from the single list_devices call # Don't call get_device for each one if not needed

API Response Format

All API responses follow a consistent structure:

Success response:

Single item response:

Error response:

Example Scripts

Monitor Device Status

Control Multiple Devices

Scene Execution

Environment Variables

You can optionally use environment variables for common settings:

API Reference

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

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.