rigol-oscilloscope-mcp

Un servidor MCP (Model Context Protocol) que permite a los LLM (Claude, Codex, etc.) controlar osciloscopios RIGOL a través de SCPI (LAN / USB) — conectar, configurar canales/base de tiempo/disparo, medir, capturar formas de onda y capturas de pantalla, decodificar protocolos seriales, ejecutar análisis FFT en el host y controlar el AFG integrado, todo a través de herramientas semánticas con una política de seguridad de cuatro niveles. Verificado en un RIGOL MHO98 real; otros modelos RIGOL funcionan con el mejor esfuerzo mediante perfiles de dispositivo. La documentación está actualmente en japonés.

Un servidor MCP para operar osciloscopios RIGOL desde un LLM.

Instrucciones en lenguaje natural como «haz visible la forma de onda de 1 kHz 3 V con una sonda x10» o «captura y guarda la forma de onda actual» son convertidas por el LLM (Claude / Codex, etc.) en llamadas a herramientas MCP, y este servidor controla el instrumento mediante SCPI (LAN / USB). No se utiliza la operación automática de GUI.

• Verificado en hardware real con RIGOL MHO98 (→ docs/verification/mho98-mvp.md)

• Otros modelos RIGOL se manejan con el mejor esfuerzo mediante perfiles de dispositivo (los modelos desconocidos funcionan con el perfil genérico y se indica explícitamente)

• Los proveedores que no sean RIGOL no están soportados (se devuelve una advertencia al conectar, pero no se rechaza)

Características

• Conexión basada en conversación — La conexión se indica principalmente mediante conversación del usuario (connect(address="...")). Los valores predeterminados de las variables de entorno son un respaldo opcional.

• 26 herramientas MCP — Conexión / identificación / obtención de estado / medición / forma de onda / análisis (estadísticas y FFT) / captura de pantalla / configuración de canal, base de tiempo y disparo / Run, Stop, Single y Autoset / configuración de decodificación serial y obtención de resultados / configuración del generador de señales (AFG), obtención de estado y control de salida (la activación de salida incluye un flujo de confirmación). No se le pide al LLM que escriba cadenas SCPI; solo se exponen herramientas semánticas.

• Política de seguridad de 4 clases + token de confirmación — Todas las operaciones se clasifican en READ_ONLY / SAFE_WRITE / RESTRICTED_WRITE / DANGEROUS_WRITE. La entrada de 50 Ω y Auto Setup requieren una confirmación de dos pasos independiente de la UI del host (token de confirmación).

• Guardado de capturas de pantalla — Se guardan en la ruta especificada en png / jpg / bmp / webp y la imagen también se devuelve al LLM (la ubicación de escritura está restringida por rutas permitidas).

• Perfiles de dispositivo — Se declaran en YAML incluido el dialecto SCPI, la disponibilidad de funciones y los rangos de parámetros, y se resuelven en tres capas: coincidencia exacta del modelo → familia → RIGOL genérico.

• Devolución de valores solicitados / aplicados — Dado que el instrumento puede ajustar los valores de configuración según el modelo, se devuelven tanto el valor solicitado como el valor leído.

• Registro de auditoría — Las operaciones de escritura se registran en JSONL con Before / Action / After.

Related MCP server: Rigol DHO824 MCP Server

Instalación y arranque

Se utiliza como estándar el arranque con uvx desde el repositorio de GitHub.

uvx --from git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0 rigol-oscilloscope-mcp

Por defecto, la versión está fijada a la etiqueta (@v0.1.0). Si se quiere usar la última versión de desarrollo (main), quitar @v0.1.0.

Claude Code — Plugin (recomendado)

Este repositorio también funciona como plugin de Claude; además del servidor MCP, se instalan simultáneamente las habilidades de flujo de trabajo de medición (configuración recomendada por tipo de señal, procedimientos de medición para UART/señales desconocidas y avisos de seguridad). Se instala después de agregar el marketplace (después de @ va el nombre del marketplace):

/plugin marketplace add zinntikumugai/rigol-oscilloscope-mcp
/plugin install rigol-oscilloscope@rigol-oscilloscope-mcp

Claude Code (.mcp.json o claude mcp add)

{
  "mcpServers": {
    "rigol-oscilloscope": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0", "rigol-oscilloscope-mcp"],
      "env": { "RIGOL_MCP_SCREENSHOT_DIR": "~/scope-captures" }
    }
  }
}

Codex — Plugin

También se incluye un plugin de Codex (.codex-plugin/ + definición de marketplace), que permite instalar de una vez el servidor MCP y las habilidades de flujo de trabajo de medición.

codex plugin marketplace add zinntikumugai/rigol-oscilloscope-mcp
codex plugin install rigol-oscilloscope

(Si no se usa el plugin, solo las habilidades se pueden copiar skills/measurement-workflows a ~/.agents/skills/ y serán reconocidas. Si solo se necesita el servidor MCP, basta con la siguiente configuración de config.toml)

Codex (~/.codex/config.toml)

[mcp_servers.rigol-oscilloscope]
command = "uvx"
args = ["--from", "git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0", "rigol-oscilloscope-mcp"]

[mcp_servers.rigol-oscilloscope.env]
RIGOL_MCP_SCREENSHOT_DIR = "~/scope-captures"

Al iniciar desde un clon local

Cuando se clona el repositorio localmente y se usa la versión de desarrollo, se inicia con uv run --directory.

{
  "mcpServers": {
    "rigol-oscilloscope": {
      "command": "/path/to/uv",
      "args": ["run", "--directory", "/path/to/rigol-oscilloscope-mcp", "rigol-oscilloscope-mcp"],
      "env": { "PYTHONDONTWRITEBYTECODE": "1" }
    }
  }
}

• command se escribe con ruta absoluta si uv no está en el PATH del host GUI (aplicación de escritorio). La ruta se verifica con which uv (o mise which uv si se usa mise).

• Se especifica explícitamente PYTHONDONTWRITEBYTECODE=1. Al iniciar desde fuera del proyecto, el [env] de mise.toml no se aplica, por lo que se evita que se escriba __pycache__ dentro del clon.

• El directorio de guardado predeterminado de capturas de pantalla es el directorio de ejecución donde se inició el servidor, no el directorio al que se movió con --directory. Si se quiere fijar, especificar RIGOL_MCP_SCREENSHOT_DIR.

• Si se pasa una ruta relativa a path, también se toma como base este directorio de guardado predeterminado. No se puede guardar fuera del directorio predeterminado, RIGOL_MCP_ALLOWED_DIRS o el directorio temporal (se rechaza).

Configuración (variables de entorno)

Toda la configuración se puede especificar mediante variables de entorno (también se puede usar opcionalmente un archivo de configuración TOML). El orden de prioridad es argumentos de herramienta (instrucciones del usuario en la conversación) > variables de entorno > archivo de configuración > valores predeterminados integrados.

Los detalles están en el capítulo 9 de docs/Requirements.md.

Probar sin hardware real

Si se inicia con RIGOL_MCP_FAKE=1, se conecta al FakeScope integrado en lugar del hardware real. Se puede verificar la configuración MCP del host y el flujo de conversación sin preparar un osciloscopio.

RIGOL_MCP_FAKE=1 uvx --from git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0 rigol-oscilloscope-mcp

Desarrollo

La versión de Python se gestiona con mise, y las dependencias y el entorno virtual con uv.

mise install          # Python + uv
uv sync               # 依存の解決
uv run pytest         # ユニットテスト(実機不要)
uv run rigol-oscilloscope-mcp   # stdioで起動

Las pruebas con hardware real solo se ejecutan cuando se pasa la dirección de conexión mediante variables de entorno (si no se configura, se omiten automáticamente). Nunca escribir la dirección IP del hardware real en el repositorio (tests/test_ip_guard.py lo verifica mecánicamente).

# read-only スイート(機器の設定を変更しない)
RIGOL_TEST_ADDRESS=<あなたのオシロのIP> uv run pytest -m device

# write スイート(設定変更 → read-back → 必ず復元)。二重ゲート
RIGOL_TEST_ADDRESS=<あなたのオシロのIP> RIGOL_TEST_ALLOW_WRITE=1 uv run pytest -m device_write

En <IP de tu osciloscopio> se coloca la dirección de tu propio instrumento (si se necesita un ejemplo, usar 192.0.2.x (TEST-NET-1), reservado para documentación).

Solución de problemas

Precauciones de seguridad

Muchos osciloscopios RIGOL, incluido el MHO98, no están aislados (el GND de cada entrada es común con el GND del chasis, USB, etc., categoría de medición Category I). Este servidor previene cambios de configuración peligrosos, pero no garantiza la seguridad eléctrica en sí.

• La conexión de la sonda, la conexión del clip de tierra, el voltaje real del DUT, la tensión máxima de la sonda y el estado de aislamiento no se pueden verificar desde MCP.

• La medición de la red eléctrica comercial (100 V CA, tomacorrientes, lado primario, AC mains) está fuera de alcance. No se ejecutan automáticamente procedimientos de medición con sondas pasivas normales. Se asume que un humano confirma el uso de sondas diferenciales o aisladas.

• Actualización de firmware / calibración / operaciones de servicio de fábrica / cambios de configuración de red están fuera de alcance.

Los detalles están en el capítulo 6 (requisitos de seguridad) de docs/Requirements.md.

Modelo de confianza del flujo de confirmación: La confirmación de dos pasos (token de confirmación) es un mecanismo para prevenir errores de operación y conclusiones precipitadas del LLM, no una defensa contra hosts MCP maliciosos (el token se devuelve al mismo llamador, por lo que si el host tiene intenciones maliciosas, basta con llamar dos veces para pasarlo). La seguridad física solo puede ser garantizada por el humano que gestiona «qué está cableado». Además, el token de enable_afg también está vinculado a la configuración del AFG en el momento de la emisión; si se cambia la configuración (amplitud, etc.) después de la emisión, el token se invalida.

Descargo de responsabilidad: Este software se proporciona sin garantía (LICENSE). El autor no se hace responsable de daños al instrumento, al dispositivo bajo prueba (DUT) o a los periféricos, errores en los resultados de medición, ni de cualquier daño que surja de ellos, causados por el uso de este software.

Licencia

MIT License — Copyright (c) 2026 zinntikumugai

Documentación

En docs/README.md se resume la lista de documentos y el orden de lectura.

• docs/Requirements.md — Documento de definición de requisitos (normativo)

• docs/tools.md — Catálogo de herramientas MCP

• docs/device-profiles.md — Especificación de perfiles de dispositivo

• docs/verification/ — Registro de verificación con hardware real

• docs/roadmap.md — Planes futuros