usb-analyzer-mcp

An MCP server that lets AI agents (Claude Code, Claude Desktop, or any MCP client) drive a USB protocol analyzer through the automation API of Teledyne LeCroy USB Protocol Suite.

It was developed and tested against a Voyager M310P (USB 3.2) with USB Protocol Suite 10.50. It uses only the suite's documented customer automation interface, so other analyzers that the suite supports should also work.

Not affiliated with Teledyne LeCroy. This is an independent, community project. It is not developed, endorsed, or supported by Teledyne LeCroy, Inc. "Teledyne LeCroy", "LeCroy", "Voyager", "Mercury", "Advisor" and "USB Protocol Suite" are trademarks of their respective owners and are used here only to describe compatibility.

What you need (and what this repo does not include)

• A licensed copy of USB Protocol Suite installed on Windows, and your own analyzer hardware. You get both from Teledyne LeCroy under their EULA. This repo contains none of their software, documentation, type libraries, sample scripts or traces. It talks to whatever suite you have installed, through the COM server that the suite registers.

• Python ≥ 3.12 and uv.

Your use of the vendor software is governed by your own agreement with Teledyne LeCroy, including its single-site license terms. This project's MIT license covers only the code in this repository.

Related MCP server: pico-mcp

Install

winget install astral-sh.uv
git clone https://github.com/tinyvision-ai-inc/usb-analyzer-mcp
cd usb-analyzer-mcp
uv sync

Claude Code

The repo has a project-scoped .mcp.json. Open Claude Code in the checkout and approve the usb-analyzer server. To use it from any project instead:

claude mcp add usb-analyzer --scope user -- uv run --directory C:\path\to\usb-analyzer-mcp usb-analyzer-mcp

Other MCP clients (e.g. Claude Desktop)

{
  "mcpServers": {
    "usb-analyzer": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\usb-analyzer-mcp", "usb-analyzer-mcp"]
    }
  }
}

HTTP transport (same lab only)

uv run usb-analyzer-mcp --transport streamable-http --host 127.0.0.1 --port 8765

There is no authentication. Bind it to localhost or a trusted lab network you control. Do not use it to share one licensed analyzer PC with users at other sites; check your vendor license first.

Tailscale (tailnet-only access)

scripts/serve-tailnet.ps1 binds the HTTP server to this machine's Tailscale IPv4 only, so it never listens on LAN or public interfaces. Tailscale Funnel/Serve isn't used. One-time setup, from an elevated PowerShell:

powershell -ExecutionPolicy Bypass -File scripts\install-tailnet.ps1   # firewall: tailnet ranges only + logon task
Start-ScheduledTask -TaskName "usb-analyzer-mcp (tailnet)"

Agents on other tailnet machines then add http://<machine>.<tailnet>.ts.net:8765/mcp, e.g. claude mcp add --transport http usb-analyzer http://<machine>:8765/mcp. Logs are written to %LOCALAPPDATA%\usb-analyzer-mcp\. Remove the setup with install-tailnet.ps1 -Uninstall. Every device in the tailnet can reach the server; use Tailscale ACLs to narrow that down.

Tools

⚠ These tools carry the MCP destructive annotation. The server's instructions tell agents to use them only when the user asks.

Traces are referred to by integer handles. Packet numbers are zero-based. Exports and reports go to the output directory and are also returned inline, truncated to a limit. The default output directory is <suite data folder>\mcp_output. Override it with --output-dir or USB_ANALYZER_MCP_OUTPUT_DIR.

Documented API only, by default

The server sticks to the methods described in the vendor's public Automation API manual. Members that the manual marks internal or restricted, or that it doesn't document at all, are refused. That covers raw recording-option setting IDs, the compliance and test interfaces, unit binding, CC-line power queries, and API-driven PD pause. An operator who has a reason to use them on their own licensed installation can turn them on:

$env:USB_ANALYZER_MCP_ENABLE_RESTRICTED = "1"

Example prompts

• "Which analyzer is connected, and what firmware does it run?"

• "Start a capture. I'll plug the board in. Then stop and tell me whether enumeration succeeded."

• "Open C:\traces\fail.usb and list every STALL and every packet with a CRC error, with timestamps."

• "Export the payload of the transfers on address 5, endpoint 1 IN to a binary file."

How it works

MCP client ──stdio/HTTP──> MCPServer (asyncio)
                               │  every COM call is marshalled onto
                               ▼
                         ComThread (STA, pumps messages; receives analyzer events)
                               │  pywin32
                               ▼
                    USB Protocol Suite (out-of-process COM server)
                               │
                               ▼
                          analyzer hardware

• src/usb_analyzer_mcp/com_thread.py: one apartment-threaded COM thread. COM objects never leave it.

• src/usb_analyzer_mcp/analyzer.py: a synchronous wrapper that also holds the trace-handle registry.

• src/usb_analyzer_mcp/server.py: the MCP tools.

• src/usb_analyzer_mcp/constants.py: interface enum values and the documented-member allowlist.

Behaviour notes (observed with suite 10.50 + Voyager M310P)

• Startup: the first tool call starts the suite if it isn't running, then waits up to ~20 s for the unit (usually ~4 s). A suite that was started through automation exits when the server lets go of it. Save any work in the suite GUI before you start an automated session.

• Reconnect: if the suite is closed, the next call reconnects. Trace handles are reset when that happens.

• Speed: the API's packet speed value doesn't distinguish full speed from high speed, so trace_get_packets takes speed from the suite's CSV decode.

• Errors: the per-category error collection came back empty or failed on our test traces. trace_errors uses the suite's error-summary report plus the error-flagged packets instead. The collection is still available as legacy_collection.

• Packet fields: values from the field API are masked to the field width. On one older sample trace they didn't match the GUI decode, so treat trace_export_csv / trace_export_text as the authoritative decode.

• Speed of access: per-packet calls cost ~25–40 ms because the suite runs out of process. Search and error listing use the CSV export instead, at roughly 1 s per few thousand packets.

• Licenses: analyzer_check_license needs the exact feature title shown in the suite's License dialog.

Tests

uv run pytest -m suite      # trace analysis on a sample trace from your suite install (no hardware needed)
uv run pytest -m hardware   # passive capture on a connected analyzer (no VBUS / exerciser / restart)

The tests launch the real server over stdio and use the MCP client SDK. They read sample files from your own suite installation and skip themselves if those files aren't there. Optional settings: USB_ANALYZER_EXPECT_HW="Voyager M310P", and USB_ANALYZER_LICENSE_FEATURE=<title> to check one real license.

License

MIT for the code in this repository. The vendor software it automates is licensed separately by its owner.