# Particle IoT MCP

> Particle IoT connects your AI agent directly to physical hardware. You read real-time sensor data (temp, moisture), check device status, and run remote functions on actuators—all through natural conversation. It’s a fleet manager for your entire connected device setup.

## Overview
- **Category:** the-unthinkable
- **Price:** Free
- **Tags:** sensor-monitoring, device-management, remote-control, firmware-updates, real-time-data, embedded-systems

## Description

Listen up. This Particle IoT MCP Server connects your AI client directly to physical hardware, giving you full remote control over any connected device setup. You're not just reading data; you're managing an entire fleet of machinery through plain conversation. It handles everything from checking a single sensor reading to running complex firmware cycles on multiple units.

When you use this server, your AI agent can immediately get the layout of your hardware with `get_devices`, listing every connected unit by its ID, name, current firmware version, and when it last checked in. You'll also find that for a deeper dive into a specific machine's parameters, running `get_device_info` pulls up all its unique capabilities and variables right away.

If you need to quickly check if a single unit is alive or responsive, use `ping_device`. It runs a simple heartbeat check on any specified device, giving you an instant status report. If the connection seems spotty, you can also get granular details about connectivity using `get_device_info`.

For monitoring actual sensor data, your agent calls `read_variable`, which pulls the live measurement—like temperature or soil moisture percentages—from any cloud variable defined on a particular device. You don't have to guess what it measures; you just ask for the specific variable and get the number back.

When you need to make something *do* stuff, `call_function` runs pre-written firmware commands directly on the hardware. This means activating an irrigation pump or kicking off a system calibration cycle with a single command. You've got total control over the physical actuators. 

For keeping your data clean and organized, you can use `rename_device` to change the user name of any device in the fleet management console. If a piece of gear is retired or sold off, running `unclaim_device` permanently removes it from your account.

To send alerts that outside systems need to listen for—say, 'low battery' or 'overheat detected'—you use `publish_event`. This sends a custom, named event directly to the cloud, triggering webhooks or logging in whatever external system you run. Finally, if you just want to make sure your AI client is aware of all connected units and their current IDs, names, and status, running `get_devices` gives that full inventory list.

## Tools

### call_function
Runs pre-written firmware commands on a specific device, such as activating a pump or starting a calibration cycle.

### get_device_info
Retrieves the specific capabilities and variables for a single device so you know what it can actually do.

### get_devices
Lists all connected devices, including their IDs, names, firmware versions, and last connection time.

### ping_device
Checks if a specific device is currently online and responsive by returning its latest status heartbeat.

### publish_event
Sends a custom, named event to the cloud for logging or triggering alerts in external systems.

### read_variable
Gets the current measured value (e.g., 68%) of any sensor variable defined on a specific device.

### rename_device
Changes the user-facing name of a device for better organization in your fleet management console.

### unclaim_device
Permanently removes an owned device from your account, typically used during asset transfer or decommissioning.

## Prompt Examples

**Prompt:** 
```
Show me all my connected Particle devices and their online status.
```

**Response:** 
```
Fetching device list... Found 5 devices. Device 1: 'Greenhouse Sensor' (ID: a1b2c3) - Online, Firmware: 5.8.0, Last seen: 1 min ago. Device 2: 'Irrigation Pump' (ID: d4e5f6) - Online, Firmware: 5.8.0, Last seen: 2 mins ago. Device 3: 'Soil Moisture Node' (ID: g7h8i9) - Offline, Last seen: 3 hours ago. Device 4: 'Weather Station' (ID: j0k1l2) - Online, Firmware: 5.7.2, Last seen: 30 secs ago. Device 5: 'Tank Level Sensor' (ID: m3n4o5) - Online, Firmware: 5.8.0, Last seen: 45 secs ago. Total: 4 online, 1 offline. Would you like to troubleshoot the offline device?
```

**Prompt:** 
```
Read the current soil moisture from my greenhouse sensor.
```

**Response:** 
```
Reading variable 'soilMoisture' from device 'Greenhouse Sensor'... Current value: 68%. Status: Adequate moisture for most crops. Historical trend: Stable over the last 6 hours. Recommendation: No irrigation needed at this time. Next check recommended in 2 hours. Would you like to read the temperature as well?
```

**Prompt:** 
```
Turn on the irrigation pump for 15 minutes.
```

**Response:** 
```
Calling function 'pumpOn' on device 'Irrigation Pump' with argument '900' (15 minutes)... Result: Success (return code 1). Pump activated successfully. Estimated water delivery: 250 liters based on flow rate. Status: Pump running, will auto-shutoff in 15 minutes. Would you like me to monitor soil moisture during the irrigation cycle?
```

## Capabilities

### List all connected devices
Retrieves IDs, names, and connection status for every Particle IoT device registered to your account.

### Read real-time sensor variables
Gets the current value of any defined cloud variable, like temperature or soil moisture, from a specific unit.

### Control remote actuators and functions
Executes pre-defined firmware functions on a device—for instance, turning an irrigation pump on or triggering a system calibration.

### Check specific device connectivity
Pings a single unit to confirm its current online status and last reported time. Essential for troubleshooting.

### Broadcast custom alerts
Sends structured events (e.g., 'low moisture alert') that external systems can listen for, triggering webhooks or logging.

## Use Cases

### Diagnosing a stalled pump
The agent first runs `get_devices` to list all pumps. It notices the main pump is offline, so it calls `ping_device`. The failure confirms network trouble, saving hours of troubleshooting.

### Automating crop monitoring
A user asks for a status check: 'Is the field ready?' The agent runs `read_variable` for soil moisture and temperature. If levels are low, it uses `call_function` to activate the irrigation pump.

### Transferring assets
You're selling a sensor node. Instead of logging into the console, you ask your agent to run `unclaim_device`. The server handles the permanent removal from your inventory.

### System reporting and logging
When the main valve status changes, instead of just reading it, the system uses `publish_event` with a custom 'ValveOpen' event name. This feeds into a separate dashboard for historical tracking.

## Benefits

- Read live data without boilerplate. You don't need to write complex API calls to know what the soil moisture is; just ask, and `read_variable` gives you the current percentage.
- Full remote control of physical hardware. Need to turn on the main pump? Use `call_function`. The agent handles sending the command directly to the device firmware.
- Immediate health checks. Instead of guessing if a unit is dead, run `ping_device`. It confirms connectivity and tells you when it last checked in.
- Structured alerting. When conditions change (e.g., water level drops), use `publish_event` to send an alert that external systems can immediately act on.
- Manage the fleet easily. Use `get_devices` to see every unit connected, and use `rename_device` so your reports read 'Greenhouse Pump' instead of 'Particle-XYZ123'.

## How It Works

The bottom line is, your agent handles all the networking plumbing so you talk to physical hardware like it's a database query.

1. Subscribe to the Particle IoT MCP Server and provide your unique Particle Access Token.
2. Your AI client uses natural language (e.g., 'What is the temperature at Sensor X?').
3. The server maps the request to the appropriate tool (`read_variable`) and returns the raw sensor data or execution result.

## Frequently Asked Questions

**How do I find out what sensors a specific device can read using Particle IoT MCP Server?**
You use the `get_device_info` tool. It returns detailed information about the unit, including all available variables and functions you can interact with.

**Can I check if my whole fleet is connected using Particle IoT MCP Server?**
Yes, use `get_devices`. This lists every single device ID in your account, along with its current online status and firmware version.

**What's the difference between `read_variable` and `ping_device`?**
`ping_device` only checks if the unit is alive (online/offline). `read_variable` actually pulls a specific piece of data—like temperature or soil moisture—from that live sensor reading.

**How do I make sure my AI agent sends an alert when something happens?**
You use the `publish_event` tool. This allows you to broadcast a structured message (an event) that external systems can listen for, triggering webhooks or logging immediately.

**What if I need to change the name of one device?**
Run the `rename_device` tool. It updates the friendly display name in your console and API responses, making it easier to identify for future commands.

**What's the process if I need to transfer or remove a device using `unclaim_device`?**
It permanently removes the device from your account. You must use `unclaim_device` when you intend to sell it or decommission it entirely. The action is irreversible, so confirm ownership changes before running this tool.

**Before I call a function on a specific gadget, how do I check its capabilities using `get_device_info`?**
Run `get_device_info` first. This tells you exactly what variables and functions the device supports. Check this output to find the correct method name and required arguments for your task.

**Can I use `publish_event` to send an alert that isn't read by a physical sensor?**
Yes, `publish_event` sends data to all subscribed listeners. You can configure external webhooks or logging systems to catch these events. This lets you trigger actions outside the IoT network.

**Can my AI read sensor data from my Particle devices?**
Yes! Use the `read_variable` tool with your device ID and the variable name (e.g., temperature, humidity, soilMoisture). Your device must expose this variable in its firmware using `Particle.variable()`. The AI will return the current sensor value in real-time. You can find available variables using `get_device_info`.

**How do I remotely turn on a pump or actuator connected to a Particle device?**
Use the `call_function` tool with your device ID and the function name (e.g., pumpOn, valveOpen). The function must be exposed in your device firmware using `Particle.function()`. You can pass an optional argument (like duration or intensity) to control the actuator behavior. Check available functions with `get_device_info`.

**Can I check if my IoT device is online and responding?**
Yes! Use the `ping_device` tool to instantly check the online status of any Particle device. You can also use `get_devices` to see the online status of all your devices at once. If a device shows as offline, it may be powered off, disconnected from Wi-Fi, or experiencing firmware issues.