IDA-Instances-MCP – IDA Pro용 안정적인 다중 인스턴스 MCP 서버

무엇인가요

• ida-pro-mcp의 커스텀 포크로, AI 도구(Claude Code, Cursor, VS Code 확장 등)가 IDA Pro를 프로그래밍 방식으로 제어할 수 있는 Model-Context-Protocol (MCP) 서버를 실행합니다.
• "headless-instances" 계층을 추가하여 여러 IDA 워커가 병렬로 실행되며, 각각 고유한 격리된 데이터베이스를 가지며 단일 HTTP(또는 stdio) 엔드포인트 뒤에서 작동합니다.

상류 리포지토리 대비 주요 개선 사항

영역	개선 사항
데이터 안전성	다른 활성 세션에 속하는 .id0/.id1/.id2/.nam/.til 파일을 삭제하지 않습니다.
저장 신뢰성	idb_save에 10분 예산을 할당하여 실패한 저장도 변경 사항을 버리지 않습니다.
동시성	워커 시작 또는 정리 중 전체 서버가 블록되지 않습니다.
강건성	잘못된 JSON-RPC는 충돌 대신 적절한 오류 코드를 반환합니다.
타임아웃	프록시 타임아웃을 15분(설정 가능)으로 상향하여 긴 디컴파일이 완료됩니다.
네트워킹	포트 레이스 처리, 잠긴 SSE 쓰기, 캐시된 CORS 읽기.
리소스 제한	추적 로그는 64 MiB로 제한되며, 과도한 인수/결과는 잘립니다. 실패 큐는 제한됨.
인증	모든 HTTP 요청은 일회성 API 키(GET /key)를 제출해야 합니다.
관리 엔드포인트	/health, /sessions, /upload (바이너리 업로드, 크기 제한).
비활성 제거	IDA_MCP_IDLE_TIMEOUT 분 이상 비활성인 세션은 자동 저장 후 닫힙니다.
예외적인 종료	SIGTERM/SIGINT 수신 시 모든 열린 데이터베이스가 저장됩니다.
자가 업데이트	시작 시 GitHub 릴리스를 확인하고 키스트로크로 자동 업데이트 가능.
기본 설정	0.0.0.0:9999에서 리슨; GUI 플러그인도 0.0.0.0에 바인딩하고 동일한 API 키 사용.

작동 방식

1. 서브버비스(idalib-mcp)가 경량 HTTP 서버로 실행되며, 열린 각 IDB에 대해 별도의 워커 프로세스를 생성합니다. 각 프로세스는 헤드리스 모드로 IDA의 idalib를 로드합니다.
2. 클라이언트는 HTTP(또는 stdio)를 통해 MCP(JSON-RPC)로 통신합니다. 서브버비스는 호출을 적절한 워커로 전달하고 타임아웃을 강제하며 결과를 반환합니다.
3. 시작 시 생성된 API 키가 모든 엔드포인트를 보호하며, 키는 ~/.idapro/mcp/api_key에 저장되어 재시작 후에도 유지됩니다.

일반적인 워크플로우

# 1️⃣ IDA의 Python 환경 활성화 (uv는 추천 패키지 매니저)
uv run "/opt/idapro-9.x/idalib/python/py-activate-idalib.py"

# 2️⃣ 헤드리스 MCP 서버 시작 (기본적으로 0.0.0.0:9999에 바인딩)
uv run idalib-mcp

# 3️⃣ 일회성 API 키 가져오기
KEY=$(curl -s http://host:9999/key | jq -r .key)

# 4️⃣ 분석을 위한 바이너리 업로드
curl -H "Authorization: Bearer $KEY" \
     --data-binary @sample.elf \
     "http://host:9999/upload?filename=sample.elf"

# 5️⃣ MCP 호환 클라이언트(예: Claude Code)를 동일한 키로 서버에 연결.

인터랙티브 GUI 프록시 실행

• IDA 내부에 MCP 플러그인 설치 (Edit → Plugins → MCP).
• 터미널에서: uv run ida-pro-mcp (stdio) 또는 uv run ida-pro-mcp --transport http://127.0.0.1:9999로 GUI에서 작업하면서 동일한 HTTP API 노출.

구성 (환경 변수, 명령줄 플래그)

• IDA_MCP_MAX_WORKERS – 동시 실행 가능한 IDA 인스턴스 최대 수 (기본값 4, 0은 무제한).
• IDA_MCP_IDLE_TIMEOUT – 세션이 자동 닫히는 비활성 시간(분, 기본값 60).
• IDA_MCP_PROXY_TIMEOUT – GUI 프록시에서 워커로의 호출 타임아웃 (기본값 900초).
• IDA_MCP_API_KEY / IDA_MCP_API_KEY_FILE – 미리 생성된 키 삽입.
• 기타 다양한 설정은 오픈 시간 제한, 업로드 크기 제한, 헬스 프로브 예산 등을 제어합니다.

사용 사례

• AI 지원 리버스 엔지니어링: Claude Code, Cursor 또는 기타 LLM 기반 에이전트가 인간이 UI에 존재하지 않는 상태에서 IDA 분석(디컴파일, 심볼 이름 변경, CFG 추출)을 수행.
• 배치 분석 팜: 서버에서 수십 개의 헤드리스 IDA 워커를 시작하여 각각 별도의 바이너리를 처리하고 MCP로 조율.
• CI/CD 보안 스캔: 파이프라인에 서버를 통합하여 바이너리를 자동 업로드하고 IDA 내부에서 정적 분석 도구를 실행하며 결과를 추출.

테스트 리포지토리에는 ida-mcp-test 헬퍼가 포함되어 있으며, 샘플 ELF 바이너리에 대해 다양한 분석 카테고리로 실행하는 방법이 예시로 제공됩니다.

라이선스

• MIT (상류 ida-pro-mcp에서 상속).
• 유효한 상용 IDA Pro 라이선스 필요; 무료 버전은 지원되지 않음.

---

이 요약은 리포지토리의 README에 기반합니다.