Skip to content
mcgpib

Getting Started

This tutorial walks you through installing mcgpib, connecting to an AR488 bridge, and discovering the instruments on your GPIB bus. By the end, you will have a working MCP server that an LLM can use to talk to your test equipment.

What you will need

Section titled “What you will need”

Before starting, make sure you have:

  • An AR488 bridge — an ESP32 running AR488 firmware with a GPIB connector and SN75160/SN75161 bus drivers
  • A connection to the bridge — USB cable (serial) or WiFi network (TCP)
  • At least one GPIB instrument — a multimeter, oscilloscope, power supply, or any IEEE-488 device connected to the bus with a GPIB cable
  • Python 3.11+ with uv installed
  • Claude Code (or another MCP-compatible client)

Install mcgpib

Section titled “Install mcgpib”

  1. Quickest: run directly from PyPI

    If you just want to use mcgpib without cloning the source, uvx will fetch and run it in an isolated environment:

    Terminal window
    uvx mcgpib

    This downloads mcgpib, installs its dependencies, and starts the MCP server. Press Ctrl+C to stop it. You will configure it properly in the next step.

  2. Alternative: install from source

    If you want to modify mcgpib or run from a local checkout:

    Terminal window
    git clone https://git.supported.systems/warehack.ing/mcgpib.git
    cd mcgpib
    uv sync
    uv run mcgpib

Configure your bridge

Section titled “Configure your bridge”

mcgpib reads its configuration from a TOML file. It searches these locations in order:

  1. The path in the $MCGPIB_CONFIG environment variable
  2. ./mcgpib.toml in the current directory
  3. ~/.config/mcgpib/config.toml in your home directory

Create a configuration file for your setup. The examples below show the two transport types.

Create ~/.config/mcgpib/config.toml:

~/.config/mcgpib/config.toml
[server]
log_level = "INFO"


[[bridge]]
name = "bench-a"
transport = "serial"
port = "/dev/ttyUSB0"
baudrate = 115200
auto_scan = true
auto_identify = true
read_timeout_ms = 3000
inter_command_delay_ms = 10

Each field:

FieldPurpose
nameA unique identifier you choose for this bridge. Used in every tool call.
transport"serial" for USB connections.
portThe serial port path. On Linux this is typically /dev/ttyUSB0 or /dev/ttyACM0. On macOS, look for /dev/cu.usbserial-*.
baudrateMust match the AR488 firmware setting. The default is 115200.
auto_scanWhen true, mcgpib scans the bus for instruments immediately after connecting.
auto_identifyWhen true, sends *IDN? to each discovered listener during a scan.
read_timeout_msHow long to wait for an instrument response before timing out (milliseconds).
inter_command_delay_msPause between consecutive commands. Prevents ESP32 voltage dips under rapid bus activity.

Add to Claude Code

Section titled “Add to Claude Code”

Register mcgpib as an MCP server so Claude Code can discover and call its tools.

Terminal window
claude mcp add mcgpib -- uvx mcgpib

If your config file is not in one of the default search paths, point mcgpib to it with the environment variable:

Terminal window
MCGPIB_CONFIG=/path/to/mcgpib.toml claude mcp add mcgpib -- uvx mcgpib

Connect and scan

Section titled “Connect and scan”

With mcgpib registered, start a Claude Code session and walk through the connection. Here is what a typical first conversation looks like.

  1. Connect to the bridge

    Ask Claude to connect, or call the tool directly:

    > Connect to my GPIB bridge "bench-a"

    Claude calls connect_bridge("bench-a"). The server opens the serial port (or TCP socket), sends initialization commands to disable verbose mode and the command prompt, then reads the firmware version. If auto_scan is enabled, it also discovers instruments on the bus.

    You should see a response like:

    Connected to bench-a: AR488 GPIB controller 0.05.99
    Discovered 3 instrument(s):
      Address 1: HEWLETT-PACKARD 34401A
      Address 5: KEITHLEY INSTRUMENTS INC. 2000
      Address 22: Agilent Technologies E3631A

  2. Scan the bus manually (optional)

    If auto_scan was disabled in your config, or if you have added instruments since connecting, scan explicitly:

    > Scan the GPIB bus on bench-a

    Claude calls bus_scan("bench-a", identify=True). The bridge sends ++findlstn to poll every address from 1 to 30, then sends *IDN? to each listener to identify it.

    Bus scan on bench-a: 3 listener(s)
      Address 1: HEWLETT-PACKARD 34401A (S/N: 3146A02377)
      Address 5: KEITHLEY INSTRUMENTS INC. 2000 (S/N: 1234567)
      Address 22: Agilent Technologies E3631A (S/N: MY12345678)

  3. Verify a specific instrument

    To get detailed identification for a single instrument:

    > Identify the instrument at address 5 on bench-a

    Claude calls instrument_identify("bench-a", 5):

    Address 5 on bench-a:
      Manufacturer: KEITHLEY INSTRUMENTS INC.
      Model: 2000
      Serial: 1234567
      Firmware: A04 /A02
      Raw: KEITHLEY INSTRUMENTS INC.,2000,1234567,A04 /A02

Your bridge is connected and your instruments are discovered. You are ready to start taking measurements.

What is next

Section titled “What is next”