Balena MCP
This MCP server lets you inspect and manage Balena Cloud resources from MCP clients using a Balena API token.
Identify the authenticated Balena account.
List and inspect fleets, devices, releases, services, organizations, teams, memberships, and device types.
Create, rename, and delete fleets; set a fleet's target release.
Rename devices, set device notes, pin devices to releases or return them to fleet tracking, move devices between fleets, and delete devices.
Set release notes.
List, create, update, and delete fleet, device, service, and config variables.
List, create, update, and delete device, fleet, and release tags.
Create teams and manage team and organization memberships.
Read documented Balena OData resources with pagination, filtering, select, expand, and orderby; API keys and SSH keys are excluded.
Find devices by exact name with safe OData quoting.
Use bounded pagination: 25 records by default, up to 100.
Require
confirm: truefor deletions and high-impact changes such as fleet release pinning and device moves.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Balena MCP Which devices in fleet 42 are offline?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Balena MCP
Manage Balena fleets, devices, releases, variables, tags, teams, and organizations from Claude, VS Code, and other MCP clients. The server runs locally over stdio or remotely over token-protected Streamable HTTP.
Add to your MCP client
First, create a named API key in Balena account preferences. It has the permissions of your Balena user account. Keep it private.
Claude Desktop: Download the
.mcpbextension with the button and open it in Claude Desktop. Enter your Balena API key when prompted. The download becomes available with the first GitHub release.VS Code: Set
BALENA_API_TOKENin the environment from which VS Code starts, then use the button. Alternatively, copy the repository's.vscode/mcp.json, which prompts for the token as a password field.Claude Code: Install the marketplace plugin. It prompts for the Balena API key:
/plugin marketplace add kieksme/mcp-balena /plugin install balena-mcp@mcp-balena
To run the package directly with any stdio MCP client:
{
"mcpServers": {
"balena": {
"command": "npx",
"args": ["-y", "@kieksme/balena-mcp"],
"env": { "BALENA_API_TOKEN": "YOUR_BALENA_API_TOKEN" }
}
}
}Related MCP server: thalovant-mcp
What it can do
Area | Tools and examples |
Fleets | List and inspect fleets, create or rename a fleet, set its target release, delete a fleet |
Devices | List and inspect devices, rename, add notes, pin releases, move or delete devices |
Releases and services | Inspect releases and services, update release notes |
Variables | List, create, update, and delete fleet, device, service, and config variables |
Tags | List, create, update, and delete device, fleet, and release tags |
Organizations and teams | List organizations, teams, and members; create teams and manage memberships |
Other API resources | Read a bounded page with |
Read tools return at most 25 records by default; top accepts 1–100 and skip selects the next page. Tools that delete resources or change a whole fleet require confirm: true. The generic query tool is read-only and excludes API-key management.
Try asking your MCP client: “Show my fleets”, “Which devices in fleet 42 are offline?”, or “List the latest releases for fleet 42.”
Run over Streamable HTTP
Set two separate secrets: BALENA_API_TOKEN for Balena and MCP_HTTP_AUTH_TOKEN for clients connecting to this MCP server.
docker run --rm -p 127.0.0.1:3000:3000 \
-e BALENA_API_TOKEN=YOUR_BALENA_API_TOKEN \
-e MCP_HTTP_AUTH_TOKEN=YOUR_LONG_RANDOM_MCP_TOKEN \
ghcr.io/kieksme/balena-mcp:latestThe MCP endpoint is http://127.0.0.1:3000/mcp; GET /health provides an unauthenticated health check. Send Authorization: Bearer <MCP_HTTP_AUTH_TOKEN> on MCP requests. The server refuses HTTP mode without that token.
For a public deployment, put HTTPS in front of the container and set MCP_HTTP_ALLOWED_HOSTS to the external hostname, for example balena-mcp.example.com,localhost,127.0.0.1. No hosted service is included with the package.
The package is published as @kieksme/balena-mcp on npm and GitHub Packages. The repository remains kieksme/mcp-balena. Development and release instructions are in CONTRIBUTING.md.
Related projects
Manage your Balena Cloud infrastructure as code with the community-maintained Balena Terraform Provider by alchemaxinc. It complements Balena MCP with declarative resource management through Terraform.
License
GPL-3.0-or-later. See LICENSE.
Available Tools
41 toolsbalena_add_organization_memberC
Add a user to an organization with a membership role ID.
Inputs: role_id (required), user_id (required), organization_id (required).
balena_add_team_memberB
Add a user to a team by numeric user ID.
Inputs: team_id (required), user_id (required).
balena_create_fleetB
Create a fleet in an organization for a device type.
Inputs: name (required), device_type_id (required), organization_id (required).
balena_create_tagB
Add a tag to a device, fleet, or release.
Inputs: key (required), kind (required), value (required), owner_id (required).
balena_create_teamA
Create a team in an organization.
Inputs: name (required), organization_id (required).
balena_create_variableB
Create a named environment or config variable. Values may contain secrets; do not repeat them in chat.
Inputs: kind (required), name (required), value (required), owner_id (required).
balena_delete_deviceADestructive
Permanently delete a device from Balena.
Inputs: confirm (required), device_id (required).
balena_delete_fleetADestructive
Permanently delete a fleet. Review its devices before confirming.
Inputs: confirm (required), fleet_id (required).
balena_delete_tagADestructive
Delete one tag by ID.
Inputs: kind (required), tag_id (required), confirm (required).
balena_delete_teamBDestructive
Permanently delete a team.
Inputs: confirm (required), team_id (required).
balena_delete_variableADestructive
Delete one environment or config variable by ID.
Inputs: kind (required), confirm (required), variable_id (required).
balena_find_device_by_nameBRead-onlyIdempotent
Find devices by exact name with safe OData quoting.
Inputs: name (required), top, skip.
balena_get_deviceARead-onlyIdempotent
Get one device by numeric ID, including its current status.
Inputs: device_id (required).
balena_get_fleetARead-onlyIdempotent
Get one fleet by numeric ID.
Inputs: fleet_id (required).
balena_get_organizationARead-onlyIdempotent
Get one organization by numeric ID.
Inputs: organization_id (required).
balena_get_releaseARead-onlyIdempotent
Get one release by numeric ID.
Inputs: release_id (required).
balena_get_teamBRead-onlyIdempotent
Get one team by numeric ID.
Inputs: team_id (required).
balena_list_devicesCRead-onlyIdempotent
List devices, optionally restricted to one fleet.
Inputs: top, skip, fleet_id.
balena_list_device_typesBRead-onlyIdempotent
List supported Balena device types.
Inputs: top, skip, parent_id.
balena_list_fleetsARead-onlyIdempotent
List fleets associated with the authenticated user, excluding unrelated public fleets.
Inputs: top, skip, parent_id.
balena_list_organization_membershipsCRead-onlyIdempotent
List members of an organization.
Inputs: top, skip, parent_id.
balena_list_organizationsARead-onlyIdempotent
List organizations visible to the API token.
Inputs: top, skip, parent_id.
balena_list_releasesBRead-onlyIdempotent
List releases for a fleet.
Inputs: top, skip, parent_id.
balena_list_servicesCRead-onlyIdempotent
List services for a fleet.
Inputs: top, skip, parent_id.
balena_list_tagsARead-onlyIdempotent
List tags attached to a device, fleet, or release.
Inputs: kind (required), owner_id (required), top, skip.
balena_list_team_membershipsCRead-onlyIdempotent
List members of a team.
Inputs: top, skip, parent_id.
balena_list_teamsARead-onlyIdempotent
List teams visible to the API token.
Inputs: top, skip, parent_id.
balena_list_variablesCRead-onlyIdempotent
List environment or config variables for a fleet, device, service, or service installation.
Inputs: kind (required), owner_id (required), top, skip.
balena_move_deviceADestructive
Move a device to a different fleet. Confirm the destination fleet first.
Inputs: confirm (required), device_id (required), destination_fleet_id (required).
balena_pin_device_releaseB
Pin a device to a release, or pass null to return to fleet tracking.
Inputs: device_id (required), release_id (required).
balena_query_resourceBRead-onlyIdempotent
Read a page of a documented Balena v7 OData resource. This tool never changes data. API keys and SSH keys are excluded.
Inputs: resource (required), top, skip, expand, +3 more.
balena_remove_organization_memberADestructive
Remove one organization membership by numeric membership ID.
Inputs: confirm (required), membership_id (required).
balena_remove_team_memberCDestructive
Remove one team membership by numeric membership ID.
Inputs: confirm (required), membership_id (required).
balena_rename_deviceB
Rename a device.
Inputs: name (required), device_id (required).
balena_rename_fleetC
Rename a fleet.
Inputs: name (required), fleet_id (required).
balena_set_device_noteC
Set a device note.
Inputs: note (required), device_id (required).
balena_set_fleet_releaseADestructive
Pin an entire fleet to a release. This changes the target for all unpinned devices; confirm the fleet and release first.
Inputs: confirm (required), fleet_id (required), release_id (required).
balena_set_release_noteC
Set the note on a release.
Inputs: note (required), release_id (required).
balena_update_tagC
Update a tag value by tag ID.
Inputs: kind (required), value (required), tag_id (required).
balena_update_variableC
Update the value of an existing variable by ID.
Inputs: kind (required), value (required), variable_id (required).
balena_whoamiARead-onlyIdempotent
Show the Balena account associated with the API token.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Most tools are clearly scoped to a single resource and action, such as list_fleets, create_tag, or pin_device_release, so an agent can usually tell them apart. The main ambiguity is balena_query_resource, which overlaps with every specific list/get tool, and the release-pinning tools also require careful reading.
All tools share a consistent balena_ prefix and mostly follow a verb_noun snake_case pattern, which makes the set predictable. Minor inconsistencies between add and create, or update and set, are present but do not seriously harm usability.
At 41 tools, the surface is well beyond the typical well-scoped range and will present agents with a long selection list. The generic query_resource tool also makes many of the specialized list/get tools feel like optional convenience wrappers rather than essential additions.
The set covers the main Balena workflows well: organizations, teams, fleets, devices, releases, tags, and variables, with solid CRUD-style coverage for tags and variables. Notable gaps such as organization creation, release deletion, and remote device actions are noticeable but not fatal to the core management workflow.
Maintenance
Related MCP Connectors
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
MCP server for interacting with the Supabase platform
Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.
The official MCP Server from Mia-Platform to interact with Mia-Platform Console
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA standalone MCP server that exposes Rancher-side tools, forwards Authorization headers or uses configured credentials, and supports HTTP and stdio transports.MIT

thalovant-mcpofficial
AlicenseNot gradedqualityBmaintenanceMCP server for Thalovant control-plane and hub runtime APIs, supporting local stdio and remote Streamable HTTP with authentication and per-principal credentials.1,049 npmMIT
zynohostingofficial
AlicenseNot gradedqualityBmaintenanceEnables management of ZynoHosting sites, files, and deployments through a local stdio MCP server.735 npmMIT- AlicenseNot gradedqualityDmaintenanceEnables creation of MCP servers with both stdio and HTTP transports, providing CRUD tools, resources, and prompts for user management, along with a CLI client for testing and integration.MIT