OpenDSS MCP Server

Claude가 OpenDSSDirect.py 라이브러리를 통해 OpenDSS를 사용하여 MV/LV 배전 네트워크(병원, 건물, 중요 시설)를 모델링하고 시뮬레이션할 수 있게 해주는 MCP 서버입니다.

1. 설치

요구 사항: Python 3.10 이상.

cd opendss-mcp
python3 -m venv venv
source venv/bin/activate        # En Windows: venv\Scripts\activate
pip install -r requirements.txt

모든 것이 올바르게 임포트되는지 확인합니다:

python3 -c "import opendssdirect; import mcp; print('OK')"

Related MCP server: uam-analyst

2. 서버를 단독으로 테스트하기(선택 사항이지만 권장됨)

Claude에 연결하기 전에 포함된 사례 연구로 로직을 직접 테스트할 수 있습니다:

python3 examples/hospital_basico.py

"convergio": true가 보이고 퍼유닛 전압이 1.0에 가까우면 서버가 올바르게 작동하는 것입니다. 이 스크립트는 MV 인입, 배전 변압기, 수술실 패널(중요 부하) 및 N-1 사고 분석을 갖춘 병원을 모델링합니다 — 전체 세부 사항은 examples/hospital_basico.py의 코드를 참조하세요.

3. Claude Desktop에 연결

Claude Desktop 구성 파일을 열거나 생성하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

다음 항목을 추가하세요(프로젝트를 저장한 절대 경로로 조정하세요):

{
  "mcpServers": {
    "opendss": {
      "command": "/ruta/absoluta/a/opendss-mcp/venv/bin/python3",
      "args": ["/ruta/absoluta/a/opendss-mcp/server.py"]
    }
  }
}

Windows에서 venv Python 실행 파일의 경로는 일반적으로 ...\opendss-mcp\venv\Scripts\python.exe입니다.

Claude Desktop을 완전히 다시 시작하세요. 도구 아이콘(🔨)에 "opendss"가 연결된 서버로 표시된 것을 볼 수 있어야 합니다.

4. 사용 가능한 도구

5. Claude와의 대화형 사용 예시

연결되면 Claude에게 다음과 같은 작업을 요청할 수 있습니다:

"13.2 kV 인입, 500 kVA에서 0.4 kV로 강압하는 변압기, 50 kW 중요 부하가 있는 수술실 패널, 20 kW 조명 패널이 있는 병원을 모델링하세요. 전력 조류를 계산하고 전압이 정상 범위(±5%) 내에 있는지 알려주세요."

또는 사고 분석:

"저압 주 간선이 손실되면 어떻게 되는지 시뮬레이션하세요. 병원의 수술실 패널에 전원이 공급되지 않게 됩니까?"

또는 네트워크 시각화:

"현재 회로의 단선도를 생성하고 브라우저에서 여세요."

5.1 시각화 예시

examples/visualizar_hospital.py는 동일한 병원 모델을 구축하고 두 개의 HTML 다이어그램을 생성합니다. 하나는 정상 상태, 다른 하나는 N-1 사고 상태로, 수술실로 가는 피더 손실의 영향을 시각적으로 비교하기 위한 것입니다.

python3 examples/visualizar_hospital.py

각 버스는 퍼유닛 전압에 따라 색상이 지정된 가로 막대로 그려집니다(녹색: 0.95–1.05 pu, 노란색: 0.90–1.10 pu, 빨간색: 범위 밖 또는 무전압). 변압기, 부하(중요한 경우 빨간색) 및 발전기는 고유한 기호로 그려집니다 — 이는 일반적인 그래프가 아니라 실제 전기 공학 관례를 따르는 단선도입니다. 다이어그램을 생성하기 전에 N-1 사고를 시뮬레이션했다면 해당 스위치가 네트워크에서 사고가 발생한 정확한 지점에서 열린 상태(gap 및 "ABIERTO" 라벨 포함)로 표시됩니다.

5.2 사례 연구: 여러 패널이 있는 캠퍼스

examples/campus_hospitalario.py는 실제 병원에 더 가까운 모델을 만듭니다. 하나의 MV 인입이 세 개의 독립 변압기(수술실, 병동, 행정)에 전력을 공급하며, 각각 여러 자체 부하를 갖고 있고, 가장 중요한 패널 전용 비상 발전기도 있습니다. 또한 선로뿐만 아니라 변압기 중 하나에 대해 N-1 분석을 실행합니다.

python3 examples/campus_hospitalario.py

생성된 다이어그램(diagrama_campus.html)은 버스(원, 전압별 색상), 변압기(구리색 점선), 부하(사각형 — 중요 부하이면 빨간색), 발전기(파란색 마름모)를 시각적으로 구분하며, 측면 패널에는 회로 요약(손실, 수렴, 요소 수)도 표시됩니다.

6. 중요한 기술 참고 사항

• 전압 베이스(VoltageBases): OpenDSS는 네트워크의 전압 레벨을 명시적으로 선언해야 합니다 (Set VoltageBases=[...]

  • CalcVoltageBases) 퍼유닛 값을 올바르게 계산하기 위해 필요합니다. 서버는 변압기를 추가할 때마다 자동으로 수행합니다 — 정상 사용 중에는 이에 대해 걱정할 필요가 없습니다.

• 지속성: 모델은 MCP 서버 프로세스가 실행되는 동안 메모리에 유지됩니다. Claude Desktop을 닫으면 손실됩니다. 모델을 저장하려면 Claude에게 obtener_netlist()를 사용하고 결과 .dss 스크립트를 내보내도록 요청할 수 있습니다.

• 현재 제한 사항: 서버는 단순화를 위해 여러 기본 매개변수(R1/X1)에서 3상 평형 네트워크를 가정합니다. 미세한 불평형(단상/2상 저압에서 흔함)을 모델링하려면 도구를 영상분 파라미터(R0/X0)와 임피던스 행렬로 확장할 수 있습니다 — 이 초기 버전에는 포함되지 않습니다.

• ⚠ calcular_arc_flash는 단순화된 방법(Lee/IEEE 1584-2002)이며, IEEE 1584-2018의 완전한 실증 모델이 아닙니다. 완전한 모델의 회귀 테이블은 IEEE가 보호하는 표준의 일부이며 여기에 구현되어 있지 않습니다. Lee 방법은 물리학을 배우고 크기 정도를 추정하는 데 유용하지만, 밀폐형 캐비닛의 장비에 대해 보수적(과대 추정)인 경향이 있으며, 차단 시간은 입력 데이터로 제공됩니다(실제 보호기기의 TCC 곡선에서 계산되지 않으며, 이 MCP도 아직 모델링하지 않습니다). 실제 설비에서 EPP를 결정하기 위해 이러한 결과를 절대 사용하지 마십시오 — 이를 위해서는 자격을 갖춘 전기 엔지니어가 검토한 규범에 따른 연구(ETAP 또는 기타 검증된 소프트웨어)가 필요합니다.

7. 변경 이력

CHANGELOG.md에서 각 버전에서 추가된 도구, 적용된 수정 사항, 아직 다루지 않은 OpenDSS 요소(LoadShape, PVSystem, Storage, Capacitor, 시간대별 분석, 고조파, 토폴로지 시각화 등)에 대한 자세한 내용을 확인하세요. 이 프로젝트는 사례 연구를 하나씩 추가하며 점진적으로 확장됩니다.