SmartThings

You can run a FastMCP 2.0 server that exposes SmartThings data and actions as MCP tools, and use a lightweight Python client to interact with it. This setup enables you to query devices, locations, scenes, rules, and more, with caching and multiple transports for fast, scalable automation workflows.

How to use

Start the server, then run the client to perform actions such as listing devices, querying locations, executing scenes, and managing automation rules. Choose a transport that fits your workflow: HTTP for standard integrations, SSE for real-time updates, or STDIO for embedded, in-process usage. Cache both on the server and client sides to minimize SmartThings API calls and accelerate responses.

How to install

Prerequisites: You need Python 3.8 or higher and a working Python package manager such as pip.

Install dependencies and set up the server and client components.

# Install Python dependencies
pip install -r requirements.txt

# Start the server using HTTP transport on the default port
python SmartThingsMCPServer.py

# Alternative: start the server on a custom port with HTTP transport
python SmartThingsMCPServer.py -port 9000

# Start the server using SSE transport
python SmartThingsMCPServer.py -transport sse -port 8000

# Start the server using STDIO transport (for direct Python integration)
python SmartThingsMCPServer.py -transport stdio

# Use the client with HTTP transport and a token (example)
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action list_devices --transport http --port 8000

Configuration and security

The server uses OAuth 2.0 bearer tokens to authenticate with the SmartThings API. You should obtain a valid SmartThings API token with the appropriate scopes for the operations you intend to perform. Tokens should be kept secure and not exposed in version control.

Two common transport modes are available for connecting the client to the server: HTTP and STDIO. HTTP provides a conventional REST-like interface, while STDIO enables direct in-process usage without network overhead. Server-Side Caching and Client-Side Caching can be enabled to reduce API calls and improve response times.

Troubleshooting

If you encounter connection or authentication issues, verify that the server is running, the transport matches between client and server, and the port is accessible. Ensure your token is valid and has the required scopes for the actions you perform.

Common steps to debug: check server process, test connectivity to the port, and review client/server logs for error messages.

Available tools

list_devices

Retrieve all devices with optional filters such as capability, location, room, or device ID.

get_device

Fetch detailed information for a specific device.

update_device

Update a device's label or basic properties.

delete_device

Remove a device from the account.

execute_command

Send a command to a device component to perform an action.

get_device_status

Obtain the current status of a device.

get_device_components

List all components of a device.

get_device_capabilities

List capabilities for a device component.

get_device_health

Check the health/connectivity status of a device.

get_device_presentation

Retrieve UI presentation details for a device.

list_locations

List all locations.

get_location

Get details of a specific location.

create_location

Create a new location with coordinates and address.

update_location

Update location details such as name and coordinates.

delete_location

Delete a location.

get_location_rooms

Get all rooms within a location.

list_rooms

List all rooms in a location.

get_room

Get details for 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.

list_modes

List 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.

list_scenes

List all scenes, optionally filtered by location.

get_scene

Get details for a specific scene.

execute_scene

Execute a scene.

create_scene

Create a new scene with actions and visual properties.

update_scene

Update an existing scene.

delete_scene

Delete a scene.

list_rules

List all automation rules, optionally filtered by location.

get_rule

Get details for a specific rule.

create_rule

Create a new automation rule with conditions and actions.

update_rule

Update an existing rule.

delete_rule

Delete a rule.

execute_rule

Manually trigger execution of a rule.