Skip to main content
Glama
EPICS MCP Server

EPICS MCP Server

by infn-argus

ARGUS

ARGUS is an MCP server that gives an AI assistant a unified operational interface to an accelerator control room — not just EPICS. A single tool call like diagnose_device("QF12") transparently pulls together live PV values, archived trends, Kubernetes pod status, ArgoCD deployment state, recent logbook entries, and documentation, and returns one structured report. The LLM never needs to know (or ask) which backend answered.

ARGUS started as a fork of INFN's epics-mcp-server (a 3-tool EPICS-only proof of concept) and has been rebuilt into a modular provider → service → tool architecture. See docs/architecture.md for the full picture.

Why not just expose EPICS functions as tools?

Because a control room isn't just PVs. A device like quadrupole QF12 is a PV group, an IOC, a Kubernetes pod, a GitOps deployment, a maintenance history, and a stack of documentation — and answering "what's wrong with QF12?" means correlating all of that. ARGUS exposes ~18 high-level, intent-shaped tools instead of hundreds of thin per-backend wrappers; each tool decides internally which of EPICS, the Archiver Appliance, ChannelFinder, Kubernetes, ArgoCD, Elasticsearch, the electronic logbook, or local documentation to query (in parallel, with per-backend timeouts and graceful degradation).

Related MCP server: EPICS MCP Server

Quickstart

python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env   # at minimum, set EPICS_CA_ADDR_LIST
.venv/bin/python -m argus --transport stdio

Every provider besides EPICS is entirely optional — the server boots fine with just EPICS_CA_ADDR_LIST set; unconfigured providers report themselves as unconfigured rather than erroring, and diagnose_device() still returns a graceful partial report. See .env.example for every provider's config, and docs/providers.md for what each one talks to.

Serve over SSE instead of stdio:

.venv/bin/python -m argus --transport sse --host 0.0.0.0 --port 8000

Backward compatibility

The original 3 tools still exist, unchanged, so existing clients (including the example scripts under test/) work with zero changes:

  • get_pv_value(pv_name) → {"status": "success", "value": ...}

  • set_pv_value(pv_name, pv_value) → {"status": "success", "message": ...}

  • get_pv_info(pv_name) → {"status": "success", "info": {...}}

get_pv/set_pv are the new, richer equivalents (include timestamp and alarm severity); the legacy names are thin aliases with byte-identical input schemas, enforced by tests/tools/test_pv_tools_backward_compat.py.

Tools

Tool

What it does

get_pv / set_pv / get_pv_info

Read/write/inspect a single PV

get_pv_value / set_pv_value

Legacy aliases of get_pv/set_pv

search_pvs

Search PVs/channels by name, tag, or property (ChannelFinder)

get_device

Full device metadata: PVs, IOC, pod, namespace, rack, owner, docs

device_status

Quick health snapshot: live PVs + pod status

diagnose_device

Full cross-system diagnostic report, one call

beamline_status

Aggregate status across a group of devices

get_history

Historical trend data for a PV (Archiver Appliance)

get_alarm_history

Recent alarm-tagged logbook entries for a device

create_logbook_entry

Post a new entry to the operations logbook (as the signed-in user, when their token is forwarded)

get_logbook_entry

Read one logbook entry straight from Olog, by id or hub code (OLOG-SPARC-1234)

update_logbook_entry

Change an existing logbook entry (as the signed-in user); Olog keeps the old version

get_logs

Search historical application/IOC logs (Elasticsearch)

list_iocs

List IOCs and their Kubernetes pod status

restart_ioc

Restart an IOC's pod

machine_summary

Machine-wide IOC health + recent alarm counts

execute_procedure

Run a named, pre-approved operational procedure (scaffolded; no procedures ship yet — see ADR context)

search_documentation

Search technical documentation (local TF-IDF by default, or RAGFLOW — see providers.md)

list_beamline_devices

Structured device inventory (IOCs, zones, devgroup/devfunc) parsed from a beamline's deploy YAML, or read from the ARGUS Knowledge Hub

list_knowledge_hub_workspaces

The ARGUS Knowledge Hub workspaces this server reads from (only when the hub is configured)

get_config_history

Read a beamline config file's current content, git history, or a commit's diff (GitHub/GitLab)

search_knowledge_base

Search issues/tickets across configured repos for past problems and resolutions (GitHub/GitLab)

search_snapshots

Search/browse Phoebus save-and-restore configurations and snapshots (read-only)

get_snapshot

Read a save-and-restore configuration's PV list, or a snapshot's saved values (read-only)

create_saverestore_configuration

Create a save-and-restore configuration from devices' setpoint (+ readback) PVs, as the signed-in user

take_saverestore_snapshot

Snapshot an existing configuration (the service reads the PVs), as the signed-in user

restore_saverestore_snapshot

Restore a snapshot to the live machine, as the signed-in user; always previewed PV by PV and confirmed

check_magnet_file

Read a magnet settings file (the consoles' CSV Name,Prefix,Current,State, or the legacy .dat) against the machine now (read-only)

create_magnet_set

A magnet file into a save-and-restore configuration (if new) and a snapshot of the same name holding the file's values, as the signed-in user

apply_magnet_set

Put magnet power supplies at a snapshot's set, one pretune step towards it, all to 0 A and STANDBY, or all ON - in the consoles' order, waiting on readbacks; always previewed supply by supply and confirmed

archive_magnet_pvs

Ask the Archiver Appliance to archive a magnet set's PVs (those not archived yet)

Knowledge source: legacy YAML/RAG/Olog, or the ARGUS Knowledge Hub

The device inventory, documentation and logbook reads can each come from the ARGUS Knowledge Hub MCP server instead of the beamline's deploy YAML, a RAG and Olog:

INVENTORY_BACKEND=knowledge_hub
DOCUMENTATION_BACKEND=knowledge_hub
LOGBOOK_BACKEND=knowledge_hub
KNOWLEDGE_HUB_URL=https://argus-hub-api.example.org/mcp
KNOWLEDGE_HUB_TOKEN=argus_pat_...     # see below
KNOWLEDGE_HUB_WORKSPACES=btf         # blank = every workspace the token may read

The token is a personal access token made in the hub (My account → Personal access tokens). To read every workspace, an administrator makes it with the read and admin scopes and without fixing it to a workspace; a token with only read reads the workspaces its owner holds a role in. Tool names and result shapes are the same either way, so a YAML-backed and a hub-backed server can answer the same question side by side — see ADR 0004.

Asking as each person. With KNOWLEDGE_HUB_AS_CALLER=true the hub is called with the caller's own identity-provider access token — the X-Argus-User-Token header LibreChat fills with their INFN AAI login — instead of KNOWLEDGE_HUB_TOKEN, which is then not needed. The hub applies that person's roles, groups and restricted classes, so two people asking the same question get what each may read. Each person has their own hub session and workspace list; a call with no caller token is refused, never answered with a service token. The hub must trust the client that issued the token: its OIDC_AUDIENCE names LibreChat's client (e.g. argus-knowledge-hub,argus-librechat).

Confirmed writes

Write tools (set_pv, set_pv_value, restart_ioc, execute_procedure, create_logbook_entry, update_logbook_entry, create_saverestore_configuration, take_saverestore_snapshot, restore_saverestore_snapshot, create_magnet_set, apply_magnet_set, archive_magnet_pvs) can be confirmed in two steps, for clients that send X-Argus-Confirm-Writes: true (LibreChat's registrations do; it has no approval step of its own). The first call changes nothing: it returns confirmation_required, a plain-language preview, and a one-time confirmation_id. Only the same call repeated with that id, by the same user, within 10 minutes, runs. Clients without the header (the voice agent, which has its own operator confirmation) are unaffected, and their tool schemas are unchanged - except restore_saverestore_snapshot and apply_magnet_set, which write a whole set of the machine at once and are confirmed for every client. See argus/mcp_server/confirmation.py for what this does and doesn't guarantee.

Magnet sets

A magnet settings file - the CSV the consoles' restore and pretune displays load (Name,Prefix,Current,State, one power supply a row), or the legacy whitespace .dat (Name Current Pol StateCode, prefix from the device inventory) - is given as its text or as a path in git.

  • create_magnet_set makes the save-and-restore configuration (each supply's CURRENT_SP and STATE_SP, with CURRENT_RB/STATE_RB as readbacks) unless one of that name already exists with exactly those PVs, and a snapshot of the same name with the file's values. The model asks the user for the name; the machine is not touched.

  • apply_magnet_set writes the supplies the way the consoles do (epik8s-opi Scripts/magapply.py, ported to services/magnet_apply.py): an ON supply going to STANDBY/OFF is first brought to 0 A and switched only once |CURRENT_RB| <= zero_tolerance; states are set before currents; each phase waits for its readbacks up to timeout_s (defaults 0.1 A, 0.5 A, 30 s). Actions: set (a snapshot), pretune (one step: each supply moves 1/steps_left of the way from its setpoint now, so steps_left=1 lands on the set; the user asks for each step), standby (every supply of a configuration to 0 A and STANDBY) and on. Targets outside a setpoint's control limits are refused before anything is confirmed. The writes go through the PV gateway as this server, not as the user.

  • archive_magnet_pvs uses the Archiver Appliance's management API (<ARCHIVER_BASE_URL>/mgmt/bpl).

An apply can take up to three phase timeouts (about 90 s by default): the MCP client's request timeout must allow it (LibreChat: the server's timeout).

Development

.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pytest

Tests never require a running EPICS/Kubernetes/ArgoCD/etc. instance — every backend is mocked. See docs/developer-guide.md for how to add a new provider or tool, and docs/class-diagram.md for the object model.

EPICS Channel Access, for local testing

softIoc -d ~/EPICS/DB/test.db
caget temperature:water
caput temperature:water 100

then point ARGUS at it with EPICS_CA_ADDR_LIST=127.0.0.1 in .env.

Deploying

  • Docker: docker build -t argus . — runs python -m argus --transport stdio by default; override the command for SSE.

  • Smithery: smithery.yaml launches python -m argus --transport stdio.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Python-based server that interacts with EPICS process variables, allowing users to retrieve PV values, set PV values, and fetch detailed information about PVs through a standardized interface.
      4
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables interaction with EPICS (Experimental Physics and Industrial Control System) process variables through natural language. Supports reading PV values, setting PV values, and retrieving detailed PV information for monitoring and controlling hardware or software parameters.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with SIEMENS PLC S7-1500/1200 controllers through their JSON-RPC API, supporting authentication, tag browsing, variable read/write operations, alarm management, and diagnostic buffer access.
      13
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with natural language access to IMAS data structures and enables remote facility exploration through SSH.
      8
      Creative Commons Attribution No Derivatives 4.0 International