Instrument MCP Server

계측기(오실로스코프, 로직 분석기, 멀티미터, 파워서플라이)를 MCP를 통해 AI에 연결하는 오픈소스 서버.

자연어로 계측기를 제어하고, 측정 결과를 AI가 분석하여, 프로젝트 맥락에서 진단과 해결책을 제시합니다.

사용자: "3.3V LDO 출력에 리플이 많은 것 같아. 확인해줘"

Claude → scope_connect → scope_capture → scope_analyze_ripple

Claude: "Vpp 리플 210mV (6.4%), 주 주파수 180kHz.
        스위칭 레귤레이터 주파수와 일치하므로
        입력측 바이패스 캡 추가를 권장합니다."

요구사항

• Python 3.12+
• (실장비 모드) VISA 호환 계측기 + USB-TMC 또는 LAN 연결
• (Mock 모드) 장비 없이 가상 데이터로 모든 기능 테스트 가능

설치

git clone https://github.com/your-org/instrument-mcp-server.git
cd instrument-mcp-server
pip install -e ".[dev]"

적용 방법

1. Claude Desktop

claude_desktop_config.json에 추가:

Mock 모드 (장비 없이 테스트):

{
  "mcpServers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP",
      "env": {
        "INSTRUMENT_MCP_MOCK": "1"
      }
    }
  }
}

실장비 모드:

{
  "mcpServers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP"
    }
  }
}

설정 파일 위치:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Claude Code (CLI)

# Mock 모드
cd D:\seriouscode\app_dev\MCP
claude mcp add instrument -- python -m src.server

또는 .claude/settings.local.json에 직접 추가:

{
  "mcpServers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP",
      "env": {
        "INSTRUMENT_MCP_MOCK": "1"
      }
    }
  }
}

3. Cursor / VS Code (Copilot)

.cursor/mcp.json 또는 .vscode/mcp.json:

{
  "servers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP",
      "env": {
        "INSTRUMENT_MCP_MOCK": "1"
      }
    }
  }
}

4. Windsurf (Codeium)

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP",
      "env": {
        "INSTRUMENT_MCP_MOCK": "1"
      }
    }
  }
}

5. 범용 (FastMCP CLI)

# Mock 모드 직접 실행
INSTRUMENT_MCP_MOCK=1 python -m src.server

# Windows
set INSTRUMENT_MCP_MOCK=1 && python -m src.server

# pip install 후 entrypoint 사용
INSTRUMENT_MCP_MOCK=1 instrument-mcp

MCP Tool 목록

오실로스코프 (6개)

Tool	설명
scope_connect	VISA 주소로 오실로스코프 연결
scope_disconnect	연결 해제
scope_measure	Vpp, 주파수, Vrms 등 측정값 반환
scope_capture	파형 캡처 실행 (자동/수동 타임베이스)
scope_analyze_ripple	전원 레일 리플/노이즈 측정
scope_list_resources	연결 가능한 VISA 장비 목록

로직 분석기 (6개)

Tool	설명
logic_connect	로직 분석기 연결
logic_capture	디지털 신호 캡처
logic_decode_spi	SPI 버스 디코딩
logic_decode_i2c	I2C 버스 디코딩 (ACK/NACK 포함)
logic_decode_uart	UART 통신 디코딩
logic_check_timing	신호 타이밍 스펙 준수 검증

멀티미터 (2개)

Tool	설명
dmm_connect	멀티미터 연결
dmm_measure	VDC/VAC/IDC/RES/FREQ 등 측정

파워서플라이 (5개)

Tool	설명
psu_connect	파워서플라이 연결
psu_set_output	출력 전압/전류 설정 (Safety 검증)
psu_enable	출력 ON/OFF
psu_read_actual	실제 출력 전압/전류 읽기
psu_status	채널 설정 상태 조회

유틸리티 (1개)

Tool	설명
instrument_status	전체 장비 연결 상태 확인

안전 제한 (Safety Layer)

파워서플라이 제어에는 하드웨어 보호를 위한 안전 제한이 적용됩니다:

항목	기본값	설명
최대 전압	30V	이 이상 설정 불가
최대 전류	3A	이 이상 설정 불가
전압 스텝	5V	한 번에 변경 가능한 최대 차이
전류 스텝	1A	한 번에 변경 가능한 최대 차이
차단 명령	*RST, *CAL, SYST:PRES	위험 SCPI 명령 실행 불가

기본값 변경은 ~/.instrument-mcp/config.json:

{
  "safety": {
    "max_voltage": 12.0,
    "max_current": 1.0,
    "max_voltage_step": 3.0
  }
}

환경변수

변수	값	설명
INSTRUMENT_MCP_MOCK	1 / true	Mock 모드 활성화
INSTRUMENT_MCP_LOG_LEVEL	DEBUG / INFO / WARNING	로그 레벨

지원 장비 (Phase 1)

종류	제조사/모델	연결
오실로스코프	Rigol DS1054Z, Siglent SDS1104	USB-TMC / LAN (SCPI)
로직 분석기	Saleae Logic 8/Pro	USB (Saleae API) - Phase 2
멀티미터	Rigol DM3058, Siglent SDM3045X	USB-TMC / LAN (SCPI)
파워서플라이	Rigol DP832, Siglent SPD3303X	USB-TMC / LAN (SCPI)

SCPI 표준을 지원하는 다른 VISA 호환 장비도 대부분 동작합니다.

개발

# 테스트
python -m pytest tests/ -v

# 린트
ruff check src/ tests/

# Mock 모드 서버 실행
set INSTRUMENT_MCP_MOCK=1 && python -m src.server

프로젝트 구조

src/
├── server.py          # MCP 서버 진입점
├── config.py          # 설정 및 안전 제한값
├── safety.py          # Safety Layer (쓰기 동작 검증)
├── drivers/           # 장비 통신 드라이버
│   ├── base.py        # 추상 베이스 클래스
│   └── visa_driver.py # SCPI/VISA 드라이버
├── tools/             # MCP Tool 정의
│   ├── oscilloscope.py
│   ├── logic_analyzer.py
│   ├── multimeter.py
│   └── power_supply.py
├── mock/              # 가상 장비 드라이버 (테스트용)
│   ├── mock_scope.py
│   ├── mock_logic.py
│   ├── mock_dmm.py
│   └── mock_psu.py
└── utils/             # 파형/프로토콜 분석 유틸리티

라이선스

MIT License