EPICS Channel Access — MCP Server

Let an AI agent read, monitor and, when you allow it, carefully write EPICS process variables (PVs) over Channel Access. EPICS is the control system behind most particle accelerators, synchrotron and neutron beamlines, large telescopes, fusion experiments and many physics labs. The server uses caproto, a pure-Python CA implementation, so there is nothing to compile and no libca to install.

⚠️ Facility control systems are safety-critical. Writing a PV can move motors and sample stages, open shutters, ramp magnets or high voltage, and change cryogenic or vacuum systems. Follow your facility's rules. Get authorisation from the responsible scientist or control-room staff before enabling writes, and run with --read-only unless writes are explicitly authorised. This server is not an interlock or a personnel-protection system and never replaces them. Where possible, connect through the facility's CA gateway with its access-security rules, and limit writes with --option put_allowlist=.

Try it without hardware

uvx labmcp-epics --simulate --check

The simulator is a real Channel Access server running in-process. It is bound to 127.0.0.1 on random free ports, and the client is pointed only at that address (auto address list off), so it neither broadcasts on nor answers your network. It serves SIM:TEMP (°C, with alarm limits, following SIM:TEMP:SP while SIM:HEATER is On), SIM:MTR (a motor whose put-callback completes only when the move is done, with SIM:MTR:RBV, :DMOV, :STOP and :VELO), SIM:DET:FRAMES, SIM:SAMPLE (string), SIM:SPECTRUM (a 512-point waveform), SIM:BEAM:CURRENT and SIM:STATUS.

Connect to your control system

1. Network: your computer must reach the IOCs, or the facility's CA gateway: UDP 5064/5065 and TCP 5064 through any firewall. Most facilities put control networks behind a gateway, so ask your controls group for its address.
2. Address list: Channel Access finds PVs by UDP search. Either use your usual EPICS environment (EPICS_CA_ADDR_LIST, EPICS_CA_AUTO_ADDR_LIST), or pass it explicitly:
   bash

   uvx labmcp-epics --read-only --address 10.0.1.20 --option check_pv=SR:CURRENT --check   # one IOC / gateway
   uvx labmcp-epics --read-only --option ca_addr_list="gw1.facility.org 10.0.1.21:5064" --option check_pv=BL7:RING:I --check
   uvx labmcp-epics --read-only --option check_pv=BL7:RING:I --check                        # use the environment as-is
   

   Passing an address list switches the automatic (broadcast) list off unless you add --option auto_addr_list=yes. With --option check_pv=<a PV you know exists>, --check reads that PV and prints its value, or the reason it can't be reached. Without it, --check only confirms that the CA client starts.

Add to your MCP client

Claude Code (read-only, recommended)

claude mcp add epics -- uvx labmcp-epics --read-only --address gw1.facility.org

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, .cursor/mcp.json, …)

{
  "mcpServers": {
    "epics": {
      "command": "uvx",
      "args": ["labmcp-epics", "--read-only", "--address", "gw1.facility.org"]
    }
  }
}

Authorised writes (example: a beamline scientist lets the agent move only the sample stage and the filter wheel, and configures an emergency safe state):

uvx labmcp-epics --address 10.0.7.10 \
  --option put_allowlist='BL7:(SAMPLE:(X|Y)|FILTER:POS)' \
  --option require_ctrl_limits=true \
  --option safe_state='BL7:SAMPLE:X.STOP=1;BL7:SAMPLE:Y.STOP=1;BL7:SHUTTER:CMD=Close'

Tools

Safety limits

Override at launch, e.g. --limit max_put_batch=4. The main write guards are options, not numeric limits:

Example prompts

• "What is the storage-ring current, and are any of the BL7 vacuum gauges in alarm?"
• "Read BL7:MONO:ENERGY and its readback, and tell me the units and control limits."
• "Monitor the sample temperature for 30 s and tell me whether it is still drifting."
• "Move the sample stage X to 12.5 mm and confirm the readback when the move is done."
• "Record the detector spectrum waveform and tell me where the peak is."
• "Stop everything: apply the safe state."

Notes

• Setpoint versus readback: for motor records, NAME (VAL) is the target and NAME.RBV is the actual position. put_pv returns the value read back from the PV you wrote, so read the readback PV separately to confirm physical motion.
• Control limits come from the CA DBR_CTRL response. EPICS convention treats equal low and high limits (normally 0/0) as "not configured", and those PVs are only type-checked.
• NaN and infinity: JSON has neither. A NaN or infinite scalar value comes back as the text "nan", "inf" or "-inf", array elements as null, a limit that is NaN (EPICS 3.16+ reports unset alarm limits that way) as null, and waveform and monitor statistics leave such values out and count them (non_finite, non_finite_updates).
• Alarms: every reading includes severity (NO_ALARM, MINOR_ALARM, MAJOR_ALARM, INVALID_ALARM), status (HIHI, LOLO, UDF, COMM, …) and age_s, the time since the IOC timestamp, so stale values stand out.
• Waveforms are downsampled by block averaging to max_elements, with min/max/mean/argmax statistics. CHAR waveforms are also decoded to text (as_string), the usual EPICS long-string convention. When writing, a text value is accepted for CHAR waveforms.
• pvAccess: only Channel Access is supported. caproto 1.x implements CA only, and pvAccess would need p4p, a compiled EPICS Base binding that is deliberately not a dependency. EPICS 7 IOCs serve their records over both CA and PVA, so this covers normal records. PVA-only data (for example NTNDArray images from areaDetector's PVA plugin, or QSRV group PVs) can't be read.
• The CA client is configured through EPICS_CA_* environment variables, as in EPICS Base. The server sets them for its own process from --address/--option and restores them on disconnect. If put_allowlist holds a comma, pass it on the command line or give LABMCP_OPTIONS in its JSON form ({"put_allowlist": "BL7:(A|B){1,2}"}), because the a=1,b=2 form splits on commas.
• get_command_log records every write (caput -c NAME value) and its read-back.

Hardware verification