yiuting927/aws-iot-mcp-server

AWS IoT Shadow MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with AWS IoT Thing Shadows. This server enables AI assistants and other MCP clients to retrieve and search AWS IoT device shadow data.

Features

This MCP server provides three powerful tools for working with AWS IoT Thing Shadows:

• get_thing_shadow: Retrieve the complete shadow document for an AWS IoT Thing
• search_shadow_property: Search for a specific property in a Thing shadow using dot notation
• find_properties_by_pattern: Find all properties matching a regex pattern in shadow state

Installation

npm install
npm run build

Configuration

Set the following environment variables:

export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key

AWS IAM Permissions

Your AWS credentials need the following IAM permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:GetThingShadow",
        "iot:UpdateThingShadow"
      ],
      "Resource": "arn:aws:iot:*:*:thing/*"
    }
  ]
}

Usage

Running the Server

npm start

The server runs on stdio and is designed to be used with MCP clients like Claude Desktop.

MCP Client Configuration

Add this server to your MCP client configuration. For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aws-iot-shadow": {
      "command": "node",
      "args": ["/Users/dannychan/projects/aws-iot-mcp-server/dist/index.js"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "your_access_key_id",
        "AWS_SECRET_ACCESS_KEY": "your_secret_access_key"
      }
    }
  }
}

Available Tools

get_thing_shadow

Retrieve the complete shadow document for an AWS IoT Thing.

Parameters:

• thingName (required): The name of the IoT Thing
• shadowName (optional): The name of the shadow (defaults to classic shadow)

Example:

{
  "thingName": "my-device",
  "shadowName": "my-shadow"
}

search_shadow_property

Search for a specific property in a Thing shadow using dot notation or JSONPath.

Parameters:

• thingName (required): The name of the IoT Thing
• propertyPath (required): Path to the property (e.g., state.reported.temperature)
• shadowName (optional): The name of the shadow

Example:

{
  "thingName": "my-device",
  "propertyPath": "state.reported.temperature"
}

find_properties_by_pattern

Find all properties in a shadow that match a regex pattern.

Parameters:

• thingName (required): The name of the IoT Thing
• pattern (required): Regex pattern to match property names
• searchIn (optional): Where to search - reported, desired, or both (default)

Example:

{
  "thingName": "my-device",
  "pattern": "temp.*",
  "searchIn": "reported"
}

Development

Project Structure

• : Main server implementation
• : Project dependencies and scripts
• : TypeScript configuration

Build

npm run build

This compiles TypeScript files from src/ to dist/.

Dependencies

• @modelcontextprotocol/sdk: MCP server SDK
• @aws-sdk/client-iot-data-plane: AWS IoT Data Plane client

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.