labgrid-mcp

Drive real embedded hardware from Claude, AI editors, and any MCP client.

labgrid is the open-source framework embedded teams use to share lab hardware: boards ("places") with remotely switchable power, serial consoles, USB muxes, and flashing tools. labgrid-mcp is a Model Context Protocol server that plugs any labgrid lab into the MCP ecosystem, so agents and dev tools can work with the lab directly:

"Acquire the rk3399 board, flash last night's image, power-cycle it, and tell me whether it reaches a login prompt. Paste the console log if it doesn't."

Not only for chat: any MCP client, scripted or human-driven, gets a policy-gated remote-control surface over labgrid's mature driver ecosystem, with the reservations and ownership arbitration ad-hoc device servers don't have.

Claude driving the built-in demo lab — no hardware, one command: uvx labgrid-mcp demo

Features

• Full device lifecycle: discover, reserve, acquire, release; keepalive-backed so holds never expire mid-task
• Hardware control: power on/off/cycle, digital I/O, SD/USB mux switching
• Interactive serial console: open, read, send, close; ring-buffered
• SSH to the device: run commands, transfer files, tunnels in both directions
• Flashing (opt-in): DFU, fastboot, bootstrap loaders, image writing, all as background jobs with status/log polling
• Lab housekeeping: tags, aliases, comments, place management, change monitoring
• Safety gating: read-only mode and per-category allowlists; the irreversible families (flash, place deletion) are off by default

47 tools, 5 browseable labgrid:// resources, honest readOnly/destructive annotations on every tool.

Try it in 5 minutes (no hardware needed)

Requires uv (its bundled uvx does the rest, including provisioning Python):

uvx labgrid-mcp demo

This boots a complete fake lab on your machine: a real labgrid coordinator and exporter, one demo board with a fake power switch and a fake serial console. It prints a paste-ready .mcp.json snippet. Then ask your agent:

• "List places, then acquire demo-place"
• "Power demo-place on and read its power state"
• "Open the console on demo-place and read its output"

Ctrl-C tears everything down.

Connect your lab

No separate install step — uvx fetches labgrid-mcp from PyPI the first time it runs. (Prefer pip? pip install labgrid-mcp, then use "command": "labgrid-mcp" with no args below.)

You need a running, gRPC-era labgrid coordinator (labgrid ≥ 24; tested against 26.x) reachable from this machine.

1. Register the server with your MCP client. The server definition is the same everywhere — command uvx, args ["labgrid-mcp"], plus your LG_* env vars — only the config file location and top-level key differ. Pick your client:

{
  "mcpServers": {
    "labgrid": {
      "command": "uvx",
      "args": ["labgrid-mcp"],
      "env": { "LG_COORDINATOR": "your-coordinator-host:20408" }
    }
  }
}

{
  "mcpServers": {
    "labgrid": {
      "command": "uvx",
      "args": ["labgrid-mcp"],
      "env": { "LG_COORDINATOR": "your-coordinator-host:20408" }
    }
  }
}

{
  "mcpServers": {
    "labgrid": {
      "command": "uvx",
      "args": ["labgrid-mcp"],
      "env": { "LG_COORDINATOR": "your-coordinator-host:20408" }
    }
  }
}

{
  "servers": {
    "labgrid": {
      "command": "uvx",
      "args": ["labgrid-mcp"],
      "env": { "LG_COORDINATOR": "your-coordinator-host:20408" }
    }
  }
}

{
  "mcpServers": {
    "labgrid": {
      "command": "uvx",
      "args": ["labgrid-mcp"],
      "env": { "LG_COORDINATOR": "your-coordinator-host:20408" }
    }
  }
}

2. Restart the client so it picks up the new server.

3. Confirm it's connected — ask your agent "List the labgrid places"; you should get your lab's boards back. You're ready.

Identity works exactly like labgrid-client: set LG_HOSTNAME / LG_USERNAME, or omit them to use your real hostname/user. Security is delegated to the network (VPN / SSH tunnel), same as labgrid-client.

(Running from a clone instead of PyPI? Use "command": "uv", "args": ["run", "--directory", "/path/to/labgrid-mcp", "labgrid-mcp"].)

Run with Docker

git clone https://github.com/onurcelep/labgrid-mcp && cd labgrid-mcp
docker build -t labgrid-mcp .

{
  "mcpServers": {
    "labgrid": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "LG_COORDINATOR=your-coordinator-host:20408",
               "labgrid-mcp"]
    }
  }
}

{
  "mcpServers": {
    "labgrid": {
      "command": "ssh",
      "args": ["labhost", "docker", "run", "-i", "--rm",
               "-e", "LG_COORDINATOR=127.0.0.1:20408",
               "-e", "LG_USERNAME=your-name",
               "labgrid-mcp"]
    }
  }
}

Your first session

Just ask in plain language — the agent maps it to the right tools. A typical first workflow:

• "Which places are free right now?"
• "Acquire board-7 for me."
• "Power it on, then open the serial console and show me the boot output."
• "SSH in and run uname -a."
• "Power it off and release the board."

Read-only asks ("list places", "who's holding board-7?") work immediately. Anything that changes hardware state is gated (see below), and the two irreversible families — flashing and place deletion — stay off until you explicitly enable them.

Configuration

Safety in one paragraph: flashing and place deletion can do irreversible damage, so each needs its own explicit LABGRID_MCP_ALLOW entry. SSH tools are arbitrary command execution on the acquired board, the same trust class as a console session; LABGRID_MCP_READONLY=1 drops them along with every other gated tool (forward_list stays, since it only lists in-memory tunnel state). And a labgrid caveat worth knowing: the coordinator enforces no ownership guard on place metadata: this server refuses to edit an acquired place without force=True, but nothing can protect a place nobody holds (and an empty tag value in set_place_tags deletes that key, which is labgrid's own semantics). Details: docs/DESIGN.md §4 and §11.12.

Tools

Limitations

• No video/audio/screen capture or USB instruments (need gstreamer + physical USB; no sane MCP surface)
• No live event stream; wait_for_change long-polling instead
• Old crossbar coordinators (labgrid < 24) can't connect
• Authentication is network-level (VPN/tunnel), exactly labgrid's own model
• The real flash/mux driver step needs a real board: the job machinery is fully CI-tested against fakes, the silicon-touching step is not

Development

git clone <this-repo> labgrid-mcp && cd labgrid-mcp
uv sync
uv run pytest              # unit
uv run pytest -m integration

License

Apache-2.0. Copyright 2026 Onur Celep.

labgrid itself is LGPL-2.1-or-later and is used as a regular, unmodified dependency.