brontes-probe-mcp

A Model Context Protocol (MCP) server that gives AI assistants direct access to a debug probe — flash firmware, halt/resume, read memory, and stream ITM trace, all without leaving the conversation.

Status: 0.3.0 — first-use hardened. Session lifecycle, probe operations, ITM/SWO trace (raw + decoded export), CMSIS pack-cache recovery, and lane supervision over three concurrent transports (stdio MCP, Unix socket, loopback TCP). All seven first-adopter friction points from the 0.2.2 retrospective are addressed — see CHANGELOG.md.

Quick start

Three steps: configure, start the probe agent (macOS / pip only), connect.

Step 1 — Configure

Pick your deployment. Each section below includes a prompt you can paste directly into Claude Code to write .mcp.json automatically, or add it manually if you prefer.

Docker on Linux (recommended)

Paste into Claude Code:

Add brontes-probe-mcp to .mcp.json in this project, creating it if needed:

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--device=/dev/bus/usb",
        "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
        "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
        "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
        "-e", "CMSIS_PACK_ROOT=/packs",
        "ghcr.io/cms-pm/brontes-probe-mcp@sha256:4b919af0673dea01444d445b5a1abcef4ea904562afbb73a3b11cdd038bcf005"
      ]
    }
  }
}

Then pull the image:
docker pull ghcr.io/cms-pm/brontes-probe-mcp@sha256:4b919af0673dea01444d445b5a1abcef4ea904562afbb73a3b11cdd038bcf005

Then tell me to restart Claude Code to load the new server.

Replace sha256:4b919af0673dea01444d445b5a1abcef4ea904562afbb73a3b11cdd038bcf005 with the digest from CHANGELOG.md.

Docker on macOS (Docker Desktop)

Docker Desktop cannot pass USB devices into containers. First install the host CLI:

pip install brontes-probe-mcp

Paste into Claude Code:

Add brontes-probe-mcp to .mcp.json in this project, creating it if needed:

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
        "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
        "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
        "-e", "CMSIS_PACK_ROOT=/packs",
        "-e", "PROBE_BROKER_GDB_HOST=host.docker.internal",
        "ghcr.io/cms-pm/brontes-probe-mcp@sha256:4b919af0673dea01444d445b5a1abcef4ea904562afbb73a3b11cdd038bcf005"
      ]
    }
  }
}

Then tell me to restart Claude Code to load the new server.

pip install (no Docker, all platforms)

Pre-flight checks — these three commands should succeed before you start the agent. They cover the friction points from real first-use:

# 1. pip is available (bootstrap with ensurepip if your venv was created without it)
python -m pip --version  ||  python -m ensurepip --upgrade

# 2. arm-none-eabi-gdb is on PATH (install via your OS package manager or
#    https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)
arm-none-eabi-gdb --version

# 3. Install brontes-probe-mcp and confirm the console script is on PATH
pip install brontes-probe-mcp
brontes-probe-mcp-cli --version

If brontes-probe-mcp-cli is not found, your shell's PATH doesn't include the directory pip wrote the script to. Either re-source your venv activate script (source .venv/bin/activate) or use python -m brontes_probe_mcp / python -m brontes_probe_mcp.cli directly.

Paste into Claude Code:

Add brontes-probe-mcp to .mcp.json in this project, creating it if needed:

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "brontes-probe-mcp-cli",
      "args": ["serve"]
    }
  }
}

Then tell me to restart Claude Code to load the new server.

Step 2 — Start the probe agent (macOS and pip only)

Docker on Linux users skip this step — the container manages pyocd internally.

Run this once before each session (keep it running in the background):

# Auto-detects probe and target if exactly one probe is connected
brontes-probe-mcp-cli probe-agent start

If auto-detection fails (multiple probes, or board not recognised by pyocd):

brontes-probe-mcp-cli probe-agent start --target stm32g474 --probe-uid <uid>

session_start auto-discovers the running agent — no extra configuration needed. session_stop removes the Brontes session but leaves the agent running for reuse.

Step 3 — Connect

After restarting Claude Code (or running /mcp to reload), paste this into the conversation:

Call probe_discover to list connected debug probes. Use any board or chip
information from the results to call target_suggest and find the pyocd
target string — pyocd usually wants the full subfamily/package suffix
(for example "stm32g474ceux", not bare "stm32g474"). If target_suggest
returns no matches, call pack_update to refresh the pack index, then
pack_search to find the right CMSIS pack name, then pack_install (may
take a minute), then retry target_suggest. If pack_search or pack_install
fails with pack_index_corrupt, call pack_cache_reset to wipe and rebuild
the pyOCD pack index, then retry. Once you have the target string, call
session_start — omit probe_uid if only one probe is connected, otherwise
pass the uid from probe_discover. If you have a CMSIS pack on disk, you
can pass pack=/path/to/pack to bypass the global pack index entirely.

If you already know your target string and pack path (fastest path):

Call session_start with target="stm32g474ceux" and pack="/path/to/STM32G4xx_DFP".

What it does

Probe discovery — probe_discover, target_suggest (with local-PDSC bypass), pack_search, pack_install, pack_update, pack_cache_reset (recover from corrupt pyOCD pack index).
Session lifecycle — session_start, session_stop, session_status (reports image_digest, image_tag, protocol_version, session_id).
Probe operations — probe_program (elf / bin / hex), probe_halt, probe_resume, probe_reset (soft, hard, sw, system, core, backend_default — each maps to a documented monitor reset command and the exact command is echoed back), probe_mem_read, probe_blackbox_export (explicit range required — see below).
ITM / SWO trace — itm_stream_start, itm_stream_stop, itm_stream_export (raw bytes + decoded JSONL artifact), recent_lines (with session_id / method / lane filters).
Lane supervision — lane_status, lane_release, lane_resume.

Three transport adapters bind concurrently over one shared BrokerCore instance, controlled by PROBE_BROKER_TRANSPORTS:

Transport	Default	Use case
`stdio`	✓	MCP stdio — one AI client
`socket`	✓	Unix-domain socket — local tool access
`tcp`	—	Loopback TCP with bearer token — sandbox / Docker Desktop

CLI

The brontes-probe-mcp-cli console script manages the server and probe agent:

brontes-probe-mcp-cli --version
brontes-probe-mcp-cli --config-dump            # print resolved config as JSON

# Start all configured transports (MCP server entry point for pip install)
brontes-probe-mcp-cli serve

# Probe agent — manages the host-side pyocd gdbserver daemon
brontes-probe-mcp-cli probe-agent start [--target TARGET] [--port PORT] [--probe-uid UID]
brontes-probe-mcp-cli probe-agent status       # prints JSON; exits 1 if not healthy
brontes-probe-mcp-cli probe-agent stop [--force]

# Generic one-shot JSON-RPC client over the running Unix socket
brontes-probe-mcp-cli call session_status
brontes-probe-mcp-cli call mem_read --json '{"addr":536870912,"length":4}'
brontes-probe-mcp-cli call session_start --json '{"target":"stm32g474ceux"}'

call opens a short-lived connection to the running broker's socket, sends one envelope, prints the reply, and exits. Exit codes: 0 on a non-error response, 1 on a transport failure or {"error": ...} envelope, 2 on invalid --json input.

If --target is omitted, probe-agent start auto-detects from a connected probe. If multiple probes are attached, specify --target and --probe-uid.

Configuration

All configuration is via PROBE_BROKER_* environment variables:

Variable	Default	Description
`PROBE_BROKER_TRANSPORTS`	`stdio,socket`	Comma-separated active transports
`PROBE_BROKER_SOCKET_PATH`	`~/.brontes-probe-mcp/probe.sock`	Unix socket path
`PROBE_BROKER_TCP_HOST`	`127.0.0.1`	TCP bind address
`PROBE_BROKER_TCP_PORT`	`7172`	TCP port
`PROBE_BROKER_LANES`	`swd,itm_swo`	Active probe lanes
`PROBE_BROKER_BACKEND`	`pyocd`	Debug backend (`pyocd` or `openocd`)
`PROBE_BROKER_GDB_HOST`	`127.0.0.1`	GDB server host — set to `host.docker.internal` to connect to a host-side probe agent
`PROBE_BROKER_DEFAULT_PACK`	(none)	Default CMSIS pack path — used by `target_suggest` and `session_start` when no `pack=` argument is supplied
`PROBE_BROKER_AGENT_STATE_DIR`	`~/.brontes-probe-mcp`	Directory where `probe-agent start` writes its state file and where `session_start` looks for a running agent. If `probe-agent start --state-dir` is set to a non-default path, set this variable to match
`PROBE_BROKER_DIGEST_CHECK`	`enforce`	Image digest verification (`enforce`, `warn`, `skip`)

Flash memory snapshot (`probe_blackbox_export`)

Capture a binary snapshot of the target's memory for archiving or diff. As of 0.3.0 an explicit range is required — the previous 512 KB flash default took roughly four minutes for a 48-byte evidence slice, so we removed it. Pass exactly one of:

// (1) explicit start/end
{"tool": "probe_blackbox_export",
 "arguments": {"out": "/tmp/snapshot.bin",
               "start_addr": 134217728, "end_addr": 134742016}}

// (2) start + length
{"tool": "probe_blackbox_export",
 "arguments": {"out": "/tmp/snapshot.bin",
               "addr": 536870912, "length": 48}}

// (3) named region from the advisory registry (sram_blackbox = 0x20000000, 64 B)
{"tool": "probe_blackbox_export",
 "arguments": {"out": "/tmp/snapshot.bin", "region": "sram_blackbox"}}

Calling with none of those raises ValueError. Response includes bytes_written, snapshot_at (UTC ISO-8601), and resolved_addr / resolved_length / resolved_from_region recording exactly which range the call resolved to.

See docs/tutorials/blackbox-export.md for custom address ranges, error cases, and snapshot comparison examples.

Troubleshooting first-use

These are the friction points the 0.2.2 first adopter actually hit, with the fix path each one now has in 0.3.0:

Symptom	Likely cause	Fix
`brontes-probe-mcp-cli: command not found` after `pip install`	Console script not on `PATH`	Re-activate your venv (`source .venv/bin/activate`) or run `python -m brontes_probe_mcp.cli`
`python -m pip` not found inside a fresh venv	Venv created without `pip`	`python -m ensurepip --upgrade`
`session_start(target="stm32g474")` → target unknown	pyOCD wants the full subfamily/package string	Use `target_suggest` to get the exact string (e.g. `"stm32g474ceux"`) — or pass `pack=/path/to/STM32G4xx_DFP` if you have a local CMSIS pack
`pack_search` / `pack_install` / `target_suggest` raise `pack_index_corrupt` (`JSONDecodeError`)	pyOCD's global pack index is malformed	Call `pack_cache_reset` (wipes `~/.pyocd/packs/index/` and re-runs `pyocd pack update`), then retry
Watchdog test reports `boot_outcome=SRON` instead of the expected `WDGR`	Debug-domain reset masked the IWDG path	Read the docstring on `reset(kind=...)` — `hard`/`sw`/`system` reset the debug domain; `soft` is the right choice for IWDG firmware watchdog tests. The `reset_command_echo` and `reset_cause_hint` fields in the response confirm what actually happened
`blackbox_export` raises `ValueError: range required`	Pre-0.3.0 default range was removed	Pass `(addr, length)`, `(start_addr, end_addr)`, or `region="sram_blackbox"`
Audit log noisy across multiple sessions	`recent_lines` returned server-wide history	Pass `session_id=` (from `session_status`); also accepts `method=` and `lane=` filters
`BrokenPipeError` traceback on `Ctrl-C` shutdown	Pre-0.3.0 transport handler raised on the half-closed socket	Already fixed — quiet `DEBUG`-level log line; no action needed

Advanced deployment

Docker Compose (socket, auto-restart)

curl -fsSL https://raw.githubusercontent.com/cms-pm/brontes-probe-mcp/main/docker-compose.yml \
  -o docker-compose.yml
docker compose up -d

TCP loopback (sandbox / Docker Desktop without probe-agent)

docker run -d --name brontes-probe-mcp \
  -e PROBE_BROKER_TRANSPORTS=stdio,tcp \
  -e PROBE_BROKER_TOKEN=your-token-here \
  -p 127.0.0.1:7172:7172 \
  --device=/dev/bus/usb \
  ghcr.io/cms-pm/brontes-probe-mcp:0.3.0

Pinning by digest

Pin by digest for production — the digest is the binary-level reproducibility contract:

ghcr.io/cms-pm/brontes-probe-mcp@sha256:<digest>

Digests are published in CHANGELOG.md for each release.

Client configuration

Configure your AI client to launch the server via the MCP stdio transport.

Claude Desktop

Add the following entry to the mcpServers object in ~/Library/Application Support/Claude/claude_desktop_config.json (Linux: ~/.config/Claude/claude_desktop_config.json):

{
  "brontes-probe-mcp": {
    "command": "docker",
    "args": [
      "run", "--rm", "-i",
      "--device=/dev/bus/usb",
      "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
      "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
      "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
      "-e", "CMSIS_PACK_ROOT=/packs",
      "ghcr.io/cms-pm/brontes-probe-mcp@sha256:4b919af0673dea01444d445b5a1abcef4ea904562afbb73a3b11cdd038bcf005"
    ]
  }
}

Claude Code

Add to .mcp.json in your project root (or ~/.claude.json for global config):

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--device=/dev/bus/usb",
        "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
        "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
        "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
        "-e", "CMSIS_PACK_ROOT=/packs",
        "ghcr.io/cms-pm/brontes-probe-mcp@sha256:4b919af0673dea01444d445b5a1abcef4ea904562afbb73a3b11cdd038bcf005"
      ]
    }
  }
}

Codex

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--device=/dev/bus/usb",
        "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
        "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
        "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
        "-e", "CMSIS_PACK_ROOT=/packs",
        "ghcr.io/cms-pm/brontes-probe-mcp@sha256:4b919af0673dea01444d445b5a1abcef4ea904562afbb73a3b11cdd038bcf005"
      ]
    }
  }
}

OpenCode

Add to opencode.json in your project root:

{
  "mcp": {
    "servers": {
      "brontes-probe-mcp": {
        "type": "stdio",
        "command": "docker",
        "args": [
          "run", "--rm", "-i",
          "--device=/dev/bus/usb",
          "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
          "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
          "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
          "-e", "CMSIS_PACK_ROOT=/packs",
          "ghcr.io/cms-pm/brontes-probe-mcp@sha256:4b919af0673dea01444d445b5a1abcef4ea904562afbb73a3b11cdd038bcf005"
        ]
      }
    }
  }
}

Replace sha256:4b919af0673dea01444d445b5a1abcef4ea904562afbb73a3b11cdd038bcf005 with the pinned digest from CHANGELOG.md.

Why "Brontes"

Brontes ("Thunderer") is one of the cyclops smiths in Hephaestus's forge — the worker who hammers metal at the master's direction. The metaphor maps onto the broker's role: client code directs the operation, the broker performs the probe work.

Changelog

See CHANGELOG.md.

License

Apache-2.0. See LICENSE.

Name		Name	Last commit message	Last commit date
.astaire		.astaire
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src/brontes_probe_mcp		src/brontes_probe_mcp
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
brontes.png		brontes.png
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt

Navigation Menu

Repository files navigation

brontes-probe-mcp

Quick start

Step 1 — Configure

Docker on Linux (recommended)

Docker on macOS (Docker Desktop)

pip install (no Docker, all platforms)

Step 2 — Start the probe agent (macOS and pip only)

Step 3 — Connect

What it does

CLI

Configuration

Flash memory snapshot (`probe_blackbox_export`)

Troubleshooting first-use

Advanced deployment

Docker Compose (socket, auto-restart)

TCP loopback (sandbox / Docker Desktop without probe-agent)

Pinning by digest

Client configuration

Claude Desktop

Claude Code

Codex

OpenCode

Why "Brontes"

Changelog

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

brontes-probe-mcp

Quick start

Step 1 — Configure

Docker on Linux (recommended)

Docker on macOS (Docker Desktop)

pip install (no Docker, all platforms)

Step 2 — Start the probe agent (macOS and pip only)

Step 3 — Connect

What it does

CLI

Configuration

Flash memory snapshot (probe_blackbox_export)

Troubleshooting first-use

Advanced deployment

Docker Compose (socket, auto-restart)

TCP loopback (sandbox / Docker Desktop without probe-agent)

Pinning by digest

Client configuration

Claude Desktop

Claude Code

Codex

OpenCode

Why "Brontes"

Changelog

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Flash memory snapshot (`probe_blackbox_export`)