EG-BIM MCP

EG-BIM MCP는 Windows에서 실행 중인 EG-BIM, IntelliCAD 기반 CAD 엔진을 Model Context Protocol(MCP)로 연결하는 서버입니다. AI assistant가 도면을 조회하고, 레이어와 객체를 분석하고, 간단한 도형 작성 및 수정 명령을 실행할 수 있도록 돕습니다.

현재 서버는 Windows COM 자동화를 사용합니다. EG-BIM 또는 IntelliCAD가 실행 중이어야 안정적으로 연결됩니다.

npm으로 설치하기

이 방법은 Windows 사용자용입니다. npm은 설치와 실행을 맡고, 실제 EG-BIM MCP는 별도 가상환경에서 실행됩니다.

1. 준비 확인

• Windows 10/11
• Node.js 20 이상 (node --version)
• Python 3.12 이상 (py -3 --version)
• EG-BIM 또는 IntelliCAD 설치 및 실행

Python과 EG-BIM은 자동 설치되지 않습니다. 아직 없다면 먼저 설치하세요.

2. MCP 설치

PowerShell에서 한 번만 실행합니다.

npm install -g egbim-mcp

첫 실행 때 %LOCALAPPDATA%\egbim-mcp\venv에 Python 실행 환경이 만들어집니다.

3. broker 등록·시작 (선택)

여러 AI client가 같은 EG-BIM을 사용하려면 broker가 필요합니다. 1.0.2부터는 이 단계를 건너뛰어도 됩니다 — broker가 떠 있지 않으면 첫 MCP 호출이 알아서 띄웁니다.

아래는 로그온 시점에 미리 띄워 첫 호출을 빠르게 하고 싶을 때만 하면 됩니다. 현재 Windows 사용자 계정에만 EG-BIM MCP Broker 예약 작업을 등록합니다.

egbim-mcp setup-broker
egbim-mcp start-broker

PowerShell에서 egbim-mcp가 "이 시스템에서 스크립트를 실행할 수 없으므로" 오류로 막히면 egbim-mcp.cmd로 실행하세요. npm이 만든 .ps1 심이 Windows 기본 실행 정책(Restricted)에 걸리는 것이며, 실행 정책을 바꿀 필요는 없습니다 — 내부 스크립트는 이미 정책을 우회하므로 .cmd로 들어가면 그대로 동작합니다.

0.2.1 이하에서 이 등록이 실패했다면 아래 업데이트 절차를 따르세요.

업데이트

도면 작업을 하지 않을 때 아래 순서대로 실행하세요.

# 1. broker 종료 (예약 작업 + 자동 기동분)
Stop-ScheduledTask -TaskName 'EG-BIM MCP Broker' -ErrorAction SilentlyContinue
Get-CimInstance Win32_Process -Filter "Name like 'python%'" | Where-Object CommandLine -like '*egbim_mcp_server*--broker*' | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }

# 2. 패키지 갱신
npm i -g egbim-mcp@latest

# 3. venv 갱신 + broker 재등록·시작
egbim-mcp.cmd setup-broker
egbim-mcp.cmd start-broker

4. MCP client를 다시 시작합니다(Claude Code는 /mcp 재연결, Codex CLI는 재시작).

EG-BIM을 실행하고 도면 하나를 연 다음, 사용하는 MCP client를 아래처럼 등록하세요. 모든 client는 --proxy를 사용합니다.

Codex CLI

codex mcp add egbim -- egbim-mcp --proxy

Claude Code

claude mcp add egbim -- egbim-mcp --proxy

Gemini CLI

gemini mcp add egbim egbim-mcp -- --proxy

등록 후 AI에게 health_check를 호출해 달라고 요청하세요. connected: true, responsive: true면 설치가 완료된 것입니다.

broker가 중지된 단일 client 개발·디버깅에서만 egbim-mcp --direct를 사용하세요. 예약 작업을 해제하려면 PowerShell에서 다음을 실행합니다.

Unregister-ScheduledTask -TaskName 'EG-BIM MCP Broker' -Confirm:$false

소스에서 개발·수정하는 경우

npm 설치 대신 소스를 내려받아 작업할 때만 아래 방법을 사용합니다.

git clone https://gitea.hmac.kr/saman/EG-BIM-MCP.git
cd EG-BIM-MCP
uv sync

주요 활용 흐름

이 저장소의 MCP 서버는 아래와 같은 CAD 작업 흐름에 맞춰 사용할 수 있습니다.

| 작업 흐름 | 설명 | 관련 MCP tools | | --- | --- | --- | | CAD 연결 상태 확인 | EG-BIM 실행 여부, 활성 도면, 버전 정보를 확인합니다. | ping, get_icad_info, get_drawing_info | | 도면 관리 | 열려 있는 도면을 확인하고, 도면을 열거나 저장하거나 활성 도면을 전환합니다. | list_documents, open_drawing, save_drawing, close_drawing, activate_document | | 레이어 조사 | 도면의 레이어 목록과 속성을 확인하고, 현재 레이어를 바꿉니다. | get_layers, set_layer, set_active_layer | | 객체 수량 파악 | 특정 레이어나 객체 유형의 개수를 먼저 확인해 큰 도면 작업의 범위를 줄입니다. | count_entities | | 객체 조회 | LINE, LWPOLYLINE, TEXT, INSERT 등 객체 정보를 레이어, 유형, 영역 조건으로 조회합니다. | get_entities, get_entity | | 문자 검색 | 도면 안의 TEXT/MTEXT에서 키워드를 찾고 필요하면 해당 위치로 화면을 이동합니다. | find_text | | 도형 작성 | 선, 폴리라인, 원, 호, 단일행/다중행 문자를 생성합니다. | create_line, create_polyline, create_circle, create_arc, create_text, create_mtext | | 객체 수정 | 객체의 레이어, 색상, 선종류 등 속성을 바꾸거나 이동/복사/삭제합니다. | modify_entity, move_entity, copy_entity, delete_entity | | 일괄 편집 | 여러 객체를 한 번에 이동, 복사, 삭제합니다. | move_entities, copy_entities, delete_entities | | 블록 작업 | 블록 정의를 조회하고, 블록을 삽입하거나 속성값을 읽고 수정합니다. | get_blocks, insert_block, get_block_attributes, set_block_attribute | | 화면 제어와 캡처 | 전체 보기, 영역 확대, 재생성, 현재 CAD 화면 캡처를 수행합니다. | zoom_extents, zoom_window, regen, capture_view | | AutoLISP/명령 실행 | IntelliCAD 명령줄에 직접 명령 또는 AutoLISP 표현식을 전달합니다. | send_command, undo, redo | | 횡단면 보조 작성 | 도면 안의 횡단 기준선과 표고 문자 정보를 이용해 횡단면 작성 흐름을 보조합니다. | draw_cross_section |

Claude Code Skills

skills 폴더에는 이 MCP 서버를 실제 업무에 쓰면서 정리한 Claude Code Skill 문서가 들어 있습니다. 위 표가 "어떤 tool이 있는지"를 보여준다면, Skill은 "실제 도면에서 어떤 순서로 해야 실패하지 않는지"를 담습니다.

| Skill | 용도 | | --- | --- | | egbim-cross-section | 평면도의 측선 폴리선과 표고 문자를 읽어 횡단면을 작도합니다. | | egbim-xsection-extract | 그려진 횡단면도 시트에서 Sta-Elev 좌표를 역추출해 HEC-RAS 지오메트리나 엑셀로 만듭니다. | | autocad-dxf-egbim-fix | AutoCAD Map 3D로 저장한 DXF가 EG-BIM에서 열리지 않을 때 정리합니다. | | fix-icad-viewport-selection | 배치 탭 뷰포트가 보이는데 마우스로 선택되지 않을 때 복구합니다. |

Skill은 MCP tool이 아니라 assistant가 참고하는 절차서이므로, 설치해도 tool 목록은 바뀌지 않습니다. 설치 방법과 주의 사항은 skills/README.md를 확인하세요.

AutoLISP 보조 유틸리티

contrib/autolisp 폴더에는 EG-BIM/IntelliCAD에서 직접 로드해서 사용할 수 있는 보조 LISP가 포함되어 있습니다. 화면 영역 저장/복원, AutoCAD 도면 호환성 정리, 이미지 다중 삽입 같은 작업을 보조합니다.

자세한 내용은 contrib/autolisp/README.md를 확인하세요.

MCP client별 연결 방식

MCP는 여러 AI 도구에서 사용할 수 있지만, client마다 지원 방식이 다릅니다. 이 서버는 현재 로컬 Windows의 EG-BIM을 COM으로 제어하는 stdio 방식 MCP 서버입니다.

| Client | 현재 서버와의 궁합 | 설명 | | --- | --- | --- | | Claude Code | 권장 | 로컬 stdio MCP 서버 등록이 간단합니다. 개발/디버깅 작업에 가장 편합니다. | | Claude Desktop | 권장 | 설정 파일에 MCP 서버를 등록해 데스크톱 앱에서 사용할 수 있습니다. | | Gemini CLI | 가능 | settings.json 또는 gemini mcp add로 stdio MCP 서버를 등록할 수 있습니다. | | ChatGPT | 별도 작업 필요 | ChatGPT의 custom MCP는 주로 원격 MCP connector/API 방식입니다. 현재 로컬 stdio 서버를 그대로 붙이기보다는 HTTP/SSE 원격 서버 형태로 감싸는 작업이 필요합니다. |

Claude Code 등록 예시

claude mcp add egbim -- egbim-mcp --proxy

직접 설정 파일에 등록하는 경우 예시는 다음과 같습니다.

{
  "mcpServers": {
    "egbim": {
      "type": "stdio",
      "command": "egbim-mcp",
      "args": [
        "--proxy"
      ],
      "env": {}
    }
  }
}

Claude Desktop 등록 예시

%APPDATA%\Claude\claude_desktop_config.json에 다음 항목을 추가합니다.

{
  "mcpServers": {
    "egbim": {
      "command": "egbim-mcp",
      "args": [
        "--proxy"
      ]
    }
  }
}

Gemini CLI 등록 예시

Gemini CLI는 settings.json의 mcpServers 항목으로 MCP 서버를 등록할 수 있습니다. 사용자 설정은 일반적으로 ~/.gemini/settings.json, 프로젝트 설정은 .gemini/settings.json에 둡니다.

{
  "mcpServers": {
    "egbim": {
      "command": "egbim-mcp",
      "args": [
        "--proxy"
      ],
      "timeout": 30000,
      "trust": false
    }
  }
}

등록 후 Gemini CLI에서 /mcp list로 연결 상태를 확인합니다. 로컬 stdio 서버는 현재 폴더가 신뢰된 상태여야 정상적으로 연결 상태가 표시될 수 있습니다.

ChatGPT에서 사용하는 경우

ChatGPT와 OpenAI API도 MCP를 지원하지만, 일반적으로 공개 URL을 가진 원격 MCP 서버를 연결하는 방식입니다. 이 저장소의 기본 서버는 로컬 Windows에서 EG-BIM을 직접 조작하는 stdio 서버이므로 ChatGPT에 바로 붙이는 구조가 아닙니다.

ChatGPT에서 사용하려면 보통 아래 작업이 추가로 필요합니다.

1. 이 서버를 Streamable HTTP 또는 SSE 방식의 원격 MCP 서버로 감쌉니다.
2. 인증, 접근 제어, 네트워크 보안을 설정합니다.
3. ChatGPT의 Connectors 또는 OpenAI API의 remote MCP tool 설정에 서버 URL을 등록합니다.
4. CAD가 실행되는 Windows PC와 원격 MCP endpoint 사이의 보안 경계를 명확히 정합니다.

따라서 처음 사용하는 경우에는 Claude Code, Claude Desktop, Gemini CLI처럼 로컬 stdio MCP를 직접 지원하는 client로 먼저 연결을 확인하는 것을 권장합니다.

연결 확인

CAD를 실행하고 도면을 연 뒤, assistant에게 다음처럼 요청합니다.

EG-BIM 연결 상태 확인해줘.

정상 연결 시 ping tool은 대략 다음 형태의 응답을 반환합니다.

{
  "status": "pong",
  "drawing": "현재도면.dwg"
}

문제 해결

EG-BIM이 떠 있는데 연결에 실패할 때

EG-BIM의 COM ProgID는 설치 버전마다 다릅니다(Icad.Application.1.3.x64, Icad.Application.1.12.x64 …). 게다가 상위 버전으로 갈아끼워도 옛 버전 ProgID가 이미 사라진 CLSID를 가리킨 채 레지스트리에 남기 때문에, 이름만 보고 고르면 EG-BIM이 실행 중인데도 연결에 실패합니다.

1.0.0부터는 설치된 실행 파일(Grimi.exe)을 찾아 그 파일 버전에서 ProgID를 만들어 쓰므로 별도 설정이 필요 없습니다. 그래도 실패하면 health_check 응답의 egbim_exe와 progid_candidates를 확인하세요. egbim_exe가 null이면 설치를 찾지 못한 것이니 ProgID를 직접 지정합니다.

# 등록된 ProgID 목록 확인
Get-ChildItem 'HKLM:\SOFTWARE\Classes' -Name | Where-Object { $_ -like 'Icad.Application.*' }

# MCP client가 읽을 환경 변수로 고정
setx EGBIM_PROGID Icad.Application.1.12.x64

접속은 되는데 모든 속성이 AttributeError일 때

health_check가 "app_error": "AttributeError: Icad.Application.1.12.x64.Caption"처럼 나오고 EG-BIM이나 broker를 다시 시작해도 그대로라면 ProgID 문제가 아닙니다. EG-BIM 자동화 형식 라이브러리(IcadAuto.dll에 내장)가 레지스트리에 등록되지 않아 EG-BIM이 속성 이름을 하나도 풀지 못하는 경우입니다(HRESULT 0x8002801D, TYPE_E_LIBNOTREGISTERED). 원래 EG-BIM 설치 프로그램이 등록해야 하는데, 업그레이드 설치한 PC에서 빠지는 일이 잦습니다.

1.0.3부터는 MCP가 EG-BIM에 붙을 때 이 상태를 확인하고, Grimi.exe와 같은 폴더의 IcadAuto.dll 형식 라이브러리를 현재 사용자(HKCU)에 자동으로 등록합니다. 관리자 권한은 필요 없고, EG-BIM이나 broker를 다시 시작하지 않아도 바로 적용됩니다. health_check 응답에서 다음 항목을 확인하세요.

• typelib_registered_by_mcp: MCP가 등록한 DLL 경로입니다. 이 항목이 있으면 MCP가 HKCU 레지스트리에 썼다는 뜻입니다.
• dispatch_hresult: AttributeError에 가려져 있던 실제 오류 코드입니다.
• typelib_registered: false, typelib_error: 자동 등록에 실패한 경우입니다. 대개 IcadAuto.dll을 찾지 못한 것이니 아래처럼 직접 등록합니다.

# 등록 여부 확인 (False이면 미등록)
Test-Path 'Registry::HKEY_CLASSES_ROOT\TypeLib\{77E49E57-976B-11CF-8CCB-00A0245B09EB}'

# 직접 등록 — dll 경로는 설치 폴더에 맞게 바꿉니다
import ctypes
dll = r"C:\Program Files\Baron\EG-BIM\IcadAuto.dll"
oleaut, ptl = ctypes.OleDLL("oleaut32"), ctypes.c_void_p()
oleaut.LoadTypeLibEx(dll, 2, ctypes.byref(ptl))  # 2 = 불러오기만
oleaut.RegisterTypeLibForUser(ptl, dll, None)    # 현재 사용자(HKCU)에 등록

되돌리려면 먼저 백업한 뒤 UnRegisterTypeLibForUser로 등록을 해제합니다. 등록할 때 TypeLib 키 말고도 HKCU\Software\Classes\Interface 아래에 인터페이스 키가 함께 생기므로, TypeLib 키만 지우면 이 키들이 남습니다. 해제한 뒤에도 같은 오류가 나면 다음 연결 때 MCP가 다시 등록합니다.

reg export HKCU\Software\Classes "$env:USERPROFILE\Desktop\hkcu_classes_backup.reg"

# 등록 해제 — TypeLib·Interface 키를 등록 전 상태로 되돌립니다
import ctypes
class GUID(ctypes.Structure):
    _fields_ = [("d1", ctypes.c_ulong), ("d2", ctypes.c_ushort),
                ("d3", ctypes.c_ushort), ("d4", ctypes.c_ubyte * 8)]
g = GUID()
ctypes.OleDLL("ole32").CLSIDFromString("{77E49E57-976B-11CF-8CCB-00A0245B09EB}", ctypes.byref(g))
# 버전 1.5, SYS_WIN64(3) — 등록된 LIBID의 버전·플랫폼과 같아야 합니다
ctypes.OleDLL("oleaut32").UnRegisterTypeLibForUser(ctypes.byref(g), 1, 5, 0, 3)

broker 콘솔 창

1.0.0부터 broker 예약 작업은 pythonw.exe로 등록되어 창이 뜨지 않습니다. 이전 버전에서 만든 예약 작업은 패키지를 갱신해도 바뀌지 않으므로 egbim-mcp setup-broker를 다시 실행하세요.

창이 없는 대신 broker 로그는 %LOCALAPPDATA%\egbim-mcp\broker.log에 남습니다(1MB씩 3개 순환).

큰 도면을 열 때 C 드라이브에 쌓이는 임시 파일

EG-BIM은 래스터 이미지 xref 등을 캐시할 때 TEMPPREFIX 시스템 변수가 가리키는 폴더에 임시 파일(xbko_*.bmp 등, 개당 3MB)을 만듭니다. 기본값이 %LOCALAPPDATA%\Temp라 C 드라이브가 찹니다.

TEMPPREFIX는 읽기 전용이라 setvar로는 못 바꾸고 EG-BIM 설정을 고쳐야 합니다. 옵션 대화상자의 경로 설정에서 임시 파일 폴더를 바꾸거나, EG-BIM을 종료한 뒤 프로필 레지스트리를 직접 수정한 다음 다시 실행합니다.

$k = 'HKCU:\SOFTWARE\Baron\EG-BIM\GRM x64\Profiles\Default\Config'
Set-ItemProperty -Path $k -Name TEMPPREFIX   -Value 'D:\EGBIM_Temp'
Set-ItemProperty -Path $k -Name SAVEFILEPATH -Value 'D:\EGBIM_Temp'

SAVEFILEPATH는 자동 저장(.SV$) 위치입니다. 사용 중인 프로필 이름이 Default가 아닐 수 있으니 Profiles 아래를 먼저 확인하세요. 이 설정은 EG-BIM이 만드는 임시 파일에만 적용되며, MCP 서버가 쓰는 임시 파일은 %TEMP%를 따릅니다.

권장 작업 흐름

큰 도면에서는 바로 전체 객체를 조회하기보다 범위를 좁혀서 접근하는 편이 안전합니다.

1. ping으로 CAD 연결과 활성 도면을 확인합니다.
2. get_layers로 레이어 이름과 상태를 확인합니다.
3. count_entities로 대상 레이어/객체 수를 먼저 파악합니다.
4. 필요한 경우 zoom_window 또는 CAD 화면 조작으로 범위를 좁힙니다.
5. get_entities 또는 send_command 기반 AutoLISP로 필요한 데이터만 추출합니다.
6. 결과가 맞는지 capture_view로 CAD 화면을 함께 확인합니다.

예시 프롬프트

현재 열린 EG-BIM 도면 이름과 저장 경로를 확인해줘.

레이어 목록을 보여주고, 꺼져 있거나 잠긴 레이어가 있는지 알려줘.

#work 레이어의 LWPOLYLINE 개수를 먼저 세어줘.

도면에서 "교량"이라는 문자를 찾아서 위치와 핸들을 알려줘.

현재 화면을 캡처해서 어떤 영역이 보이는지 설명해줘.

좌표 (0, 0)에서 (100, 0)까지 TEMP 레이어에 선을 하나 그려줘.

선택한 객체의 핸들을 기준으로 레이어를 CHECK로 바꿔줘.

AutoLISP 사용 시 주의 사항

• IntelliCAD 9.x 계열에서 vlax-* 지원은 빌드마다 다르고 부분적입니다. 아래는 EG-BIM 1.5.1.0 (ACADVER 19.0i)에서 실제로 호출해 확인한 결과입니다.
  • 동작 확인: vl-catch-all-apply / vl-catch-all-error-message, vlax-ename->vla-object, vlax-get-property, vla-get-Layer, vla-get-Length, vla-get-Area, vlax-curve-getEndParam / -getDistAtParam / -getPointAtDist
  • 동작 안 함: vlax-curve-getClosestPointTo, shell (외부 실행은 startapp 사용)
  • 미확정: vlax-invoke, vlax-make-safearray, vla-get-ActiveDocument
  • 다른 빌드에서는 결과가 다를 수 있으므로, 새 함수를 쓰기 전에 한 번 호출해 확인하는 것을 권장합니다.
• 오류 처리에는 vl-catch-all-apply를 쓸 수 있습니다. 이것을 쓰지 않으면 LISP 실패가 아무 신호 없이 조용히 지나갑니다.
• 가능하면 기본 AutoLISP 함수 중심으로 작성하는 것을 권장합니다.
• 큰 도면에서 전체 선택을 반복하면 CAD가 멈추거나 타임아웃될 수 있습니다.
• send_command는 명령 문자열의 끝 공백을 제거한 뒤 실행합니다. 불필요한 Enter가 이전 명령을 반복 실행하지 않도록 하기 위한 안전장치입니다.

보안 주의 사항

이 MCP 서버는 로컬 CAD를 실제로 조작할 수 있는 도구입니다. 단순 조회뿐 아니라 도면 열기, 저장, 객체 생성, 이동, 삭제, AutoLISP/명령 실행 기능을 포함합니다.

배포 또는 설치 전에 아래 원칙을 지켜 주세요.

• 신뢰할 수 있는 로컬 AI client에만 연결합니다.
• 이 서버를 인증 없이 인터넷에 공개하지 않습니다.
• 원격 MCP 서버로 감쌀 경우 반드시 인증, 접근 제어, 로그, 방화벽 정책을 먼저 설계합니다.
• 실제 업무 도면에서는 작업 전 백업을 만듭니다.
• 민감한 DWG, Excel, 스크린샷, 수량산출 자료는 공개 저장소에 올리지 않습니다.
• AI가 실행하려는 send_command, delete_entity, delete_entities, save_drawing, close_drawing 요청은 실행 전 의도를 확인합니다.
• 처음 연결 테스트는 중요 도면이 아닌 테스트 도면에서 진행합니다.

개발자 참고

이 저장소는 MCP 서버 자체를 공개 대상으로 관리합니다. 실험용 도면, 수량산출 검토 자료, 프로젝트별 분석 스크립트는 로컬 작업 공간에서 관리하고 저장소에는 포함하지 않는 것을 권장합니다.

공개 저장소에 올리기 전 확인할 항목은 다음과 같습니다.

• DWG, GBK, BAK 등 CAD 원본/백업 파일 제외
• 프로젝트별 임시 CSV/TXT/PNG 제외
• 민감한 도면명, 좌표, 발주처 정보 포함 여부 확인
• 큰 도면 작업은 count_entities로 규모 확인 후 진행

참고 문서

• OpenAI: Building MCP servers for ChatGPT and API integrations
• OpenAI: Connectors and MCP servers
• Gemini CLI: MCP servers

License

MIT