# Balena MCP for AI Agents MCP

> Balena MCP gives your AI client direct access to manage entire IoT infrastructures and edge device fleets. Check device statuses, deploy environment variable updates, track software releases across multiple applications, and query specific hardware details—all without opening a dashboard.

## Overview
- **Category:** cloud-infrastructure
- **Price:** Free
- **Tags:** fleet-management, edge-computing, device-monitoring, linux-devices, deployment-automation, remote-management

## Description

Managing physical devices spread out in the real world is usually a nightmare of dashboards, filters, and tedious clicking. This MCP lets your AI client bypass that pain entirely. You talk to it naturally, and it runs complex commands against your entire BalenaCloud setup. Need to know if all 50 cameras are running v2.115? Ask the agent. Want to tag a specific sensor node with its physical location? Have it do it. This connectivity allows you to monitor device health, manage fleet configurations, and handle deployments directly from your chat interface. Because this MCP lives on Vinkius, you connect once—whether that's through Cursor or Claude—and instantly gain access to the entire catalog of enterprise tools.

## Tools

### list_api_keys
Lists all API keys associated with your Balena account for management and auditing.

### create_device_env_var
Sets or modifies a specific environment variable on an individual device's operating system.

### create_device_tag
Applies a custom metadata tag to a physical device for better organization and grouping.

### list_devices
Queries devices within specific fleets using advanced filtering methods like UUID or status.

### list_fleets
Lists all application groups (fleets) hosted on your account, allowing you to scope device queries.

### get_os_download_url
Retrieves the direct download URL for a specific balenaOS image optimized for a given hardware type.

### list_os_versions
Presents an inventory of all available operating system versions compatible with a chosen device model.

### list_organizations
Provides a list of distinct organizational units within your Balena account structure.

### list_releases
Checks the deployment history and available releases for specific application fleets.

### whoami
Retrieves basic information about your current user profile within BalenaCloud.

## Prompt Examples

**Prompt:** 
```
Show me which devices in my sensor fleet are running the old OS version.
```

**Response:** 
```
**Device Status Report: Sensor Fleet (20 nodes)**

| Device ID | Current Version | Last Seen | Status |
| :--- | :--- | :--- | :--- |
| 1a3b-c4d5 | v2.108.27 | 2024-06-01 | Online |
| 9e8f-g7h6 | v2.108.27 | 2024-06-01 | Online |
| 3c2b-a1d2 | **v2.115.18** | 2024-06-12 | Offline (Needs Update) |

*Action Required: Device 3c2b-a1d2 needs an OS update to match the current stable release.*
```

**Prompt:** 
```
Can you find me a download link for the latest OS image for my RPi4?
```

**Response:** 
```
I found several versions available for the Raspberry Pi 4 (64-bit). The most recent stable releases are:

*   **v2.115.18**: Download URL: `https://balena-download/rpi4-2.115`
*   **v2.113.18**: Download URL: `https://balena-download/rpi4-2.113`

You can use the link for v2.115.18 to start your build immediately.
```

**Prompt:** 
```
I need to update the location tag and add a new API key variable to all devices in the warehouse.
```

**Response:** 
```
**Update successful!**

*   ✅ Tag 'Location: Warehouse-B' applied to 15/20 nodes.
*   🔑 Environment Variable `REPORTING_KEY` successfully set for all scoped devices. The previous key has been overwritten with the new value.
```

## Capabilities

### Querying Device Status and Location
Retrieve comprehensive lists of all devices or specific fleets by applying detailed filters, letting you quickly check the status of hardware units.

### Managing Device Metadata
Add or update custom tags and environment variables on individual edge devices to keep your physical inventory organized.

### Tracking Software Deployments
Inspect deployment history and check release versions across different applications to confirm that all hardware is running the required software build.

### Retrieving OS Images
Query available operating system versions for specific device types and get direct download URLs for rapid prototyping or updates.

### Inspecting Account Details
Verify your current user profile, associated organizations, and active API keys to manage your account permissions.

## Use Cases

### Emergency Device Audit
A sensor fails in a remote location. Instead of logging into the dashboard, the engineer asks their agent to 'List all devices in the factory floor fleet that are offline.' The agent uses `list_devices` and immediately provides a filtered list with specific UUIDs.

### Mass Configuration Update
The team needs to update every device's reporting key. They ask the agent to 'Set the new API key variable for all nodes in the warehouse fleet.' The MCP uses `create_device_env_var` across the entire scope, saving hours of manual updates.

### Pre-Deployment Setup
A project requires a specific OS version. The product owner asks their agent, 'What are the available balenaOS versions for my Raspberry Pi 4?' The MCP uses `list_os_versions` and provides the necessary download URLs.

### Compliance Check
The team needs proof that all edge nodes run the stable production build. They ask the agent to 'Show me the latest release status for the critical sensor fleet.' The MCP calls `list_releases` and confirms adherence.

## Benefits

- Eliminate dashboard hopping. Instead of navigating multiple tabs to check device status, you just ask the agent, which runs advanced queries via `list_devices`.
- Maintain strict hardware organization. Use the MCP to dynamically add metadata tags or environment variables to devices using `create_device_tag` and `create_device_env_var`, keeping your inventory clean.
- Accelerate development cycles. Quickly find necessary images for prototyping by calling `list_os_versions` and getting direct URLs via `get_os_download_url`.
- Simplify compliance checks. Periodically verify that all deployed hardware is running the required software version by inspecting releases using `list_releases`.
- Understand your scope immediately. Use `list_fleets` to see every application group you manage, and `whoami` to confirm which organization context the agent is working in.

## How It Works

The bottom line is: you get instant, programmatic control over complex edge device environments without ever touching a web console.

1. Subscribe to this MCP on Vinkius and provide your Balena API Key.
2. Your AI client authenticates the connection, giving it read/write access to your cloud infrastructure data.
3. You instruct your agent using natural language (e.g., 'List all devices in the industrial fleet that are currently offline').

## Frequently Asked Questions

**How do I check if my remote IoT hardware is running the right software version using Balena MCP?**
You can confirm compliance by asking your agent to list releases for a specific fleet. This tells you exactly what versions are available and which ones should be deployed, helping you verify that all nodes match the required build.

**Can Balena MCP help me organize my physical device inventory? **
Yes. You can use the agent to add custom tags or environment variables to specific devices, acting like a programmatic way to label and categorize your hardware without logging into the dashboard.

**What if I need an OS image for a new project? Can Balena MCP help me get it?**
The agent can list all operating system versions compatible with your specific device type, giving you direct download URLs right in the chat. This speeds up prototyping dramatically.

**Does Balena MCP let me update settings on many devices at once?**
Absolutely. You tell the agent which group of devices needs updating—like setting a new reporting key or adding a location tag—and it applies that change across all selected nodes in one go.

**Is Balena MCP only for checking status, or can I actually make changes?**
It does both. You can read the status of devices using advanced querying, but you also have write permissions to modify tags and environment variables on live hardware.