Skip to main content
Glama

Balena MCP

CI npm

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

Get for Claude Desktop Install in VS Code

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 .mcpb extension 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_TOKEN in 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 balena_query_resource using Balena OData filters

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:latest

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

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 tools
balena_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_deviceA
Destructive

Permanently delete a device from Balena.

Inputs: confirm (required), device_id (required).

balena_delete_fleetA
Destructive

Permanently delete a fleet. Review its devices before confirming.

Inputs: confirm (required), fleet_id (required).

balena_delete_tagA
Destructive

Delete one tag by ID.

Inputs: kind (required), tag_id (required), confirm (required).

balena_delete_teamB
Destructive

Permanently delete a team.

Inputs: confirm (required), team_id (required).

balena_delete_variableA
Destructive

Delete one environment or config variable by ID.

Inputs: kind (required), confirm (required), variable_id (required).

balena_find_device_by_nameB
Read-onlyIdempotent

Find devices by exact name with safe OData quoting.

Inputs: name (required), top, skip.

balena_get_deviceA
Read-onlyIdempotent

Get one device by numeric ID, including its current status.

Inputs: device_id (required).

balena_get_fleetA
Read-onlyIdempotent

Get one fleet by numeric ID.

Inputs: fleet_id (required).

balena_get_organizationA
Read-onlyIdempotent

Get one organization by numeric ID.

Inputs: organization_id (required).

balena_get_releaseA
Read-onlyIdempotent

Get one release by numeric ID.

Inputs: release_id (required).

balena_get_teamB
Read-onlyIdempotent

Get one team by numeric ID.

Inputs: team_id (required).

balena_list_devicesC
Read-onlyIdempotent

List devices, optionally restricted to one fleet.

Inputs: top, skip, fleet_id.

balena_list_device_typesB
Read-onlyIdempotent

List supported Balena device types.

Inputs: top, skip, parent_id.

balena_list_fleetsA
Read-onlyIdempotent

List fleets associated with the authenticated user, excluding unrelated public fleets.

Inputs: top, skip, parent_id.

balena_list_organization_membershipsC
Read-onlyIdempotent

List members of an organization.

Inputs: top, skip, parent_id.

balena_list_organizationsA
Read-onlyIdempotent

List organizations visible to the API token.

Inputs: top, skip, parent_id.

balena_list_releasesB
Read-onlyIdempotent

List releases for a fleet.

Inputs: top, skip, parent_id.

balena_list_servicesC
Read-onlyIdempotent

List services for a fleet.

Inputs: top, skip, parent_id.

balena_list_tagsA
Read-onlyIdempotent

List tags attached to a device, fleet, or release.

Inputs: kind (required), owner_id (required), top, skip.

balena_list_team_membershipsC
Read-onlyIdempotent

List members of a team.

Inputs: top, skip, parent_id.

balena_list_teamsA
Read-onlyIdempotent

List teams visible to the API token.

Inputs: top, skip, parent_id.

balena_list_variablesC
Read-onlyIdempotent

List environment or config variables for a fleet, device, service, or service installation.

Inputs: kind (required), owner_id (required), top, skip.

balena_move_deviceA
Destructive

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_resourceB
Read-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_memberA
Destructive

Remove one organization membership by numeric membership ID.

Inputs: confirm (required), membership_id (required).

balena_remove_team_memberC
Destructive

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_releaseA
Destructive

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_whoamiA
Read-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

    B3/5.0

    Scored across 41 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A standalone MCP server that exposes Rancher-side tools, forwards Authorization headers or uses configured credentials, and supports HTTP and stdio transports.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for Thalovant control-plane and hub runtime APIs, supporting local stdio and remote Streamable HTTP with authentication and per-principal credentials.
      1,049 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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