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.
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" }
}
}
}| 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.”
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.
GPL-3.0-or-later. See LICENSE.