Tech Guide - Installation Guide

1

시스템 요구 사항

구성 요소	최소	권장
OS	Windows 10 64-bit (Build 19041+)	Windows 11 64-bit
Python	3.10	3.12 (python.org installer)
RAM	8 GB	16 GB+
Disk	500 MB free	2 GB+ free
CPU	4 cores	8+ cores
Network	Internet required (HTTPS)	Stable broadband
AI Client	Claude Desktop or Claude Code	Claude Code (latest)
Node.js	18.x	20.x LTS

2

Python 환경 설정

SOAR MCP 커넥터는 Python 3.10 이상이 필요합니다. python.org 의 설치 프로그램을 사용하는 것을 강력히 권장합니다 (Windows Store 버전이 아닌).

# Verify Python installation / 验证 Python 安装
python --version
# Expected output: Python 3.12.x

# Verify pip is available / 验证 pip
pip --version

# Create a virtual environment (recommended) / 创建虚拟环境（推荐）
python -m venv C:\soar\venv
C:\soar\venv\Scripts\activate

# Verify activation / 验证激活
where python
# Should show: C:\soar\venv\Scripts\python.exe
            

⚠️ Windows Store Python 주의

Windows Store 버전의 Python은 파일 경로 권한 및 COM 자동화에 알려진 문제가 있습니다. 항상 python.org 설치 프로그램을 사용하고 설치 중 "Add Python to PATH"를 체크하세요.

3

종속성

각 SOAR MCP 커넥터에는 자체 종속성이 있습니다. 가상 환경을 활성화한 후 pip으로 설치하세요.

# Install SOAR MCP connector (example: AutoCAD)
pip install soar-autocad-mcp

# Or install from GitHub release
pip install https://github.com/soarmcpsoftware/soar-autocad-mcp/releases/latest/download/soar-autocad-mcp.tar.gz

# Common dependencies installed automatically:
#   - mcp (Model Context Protocol SDK)
#   - pywin32 (Windows COM automation)
#   - pydantic (data validation)
#   - httpx (HTTP client)

# Verify installation / 验证安装
pip list | findstr soar
            

Dependency	Version	용도
`mcp`	>=1.0	Model Context Protocol SDK
`pywin32`	>=306	Windows COM 자동화
`pydantic`	>=2.0	Data validation
`httpx`	>=0.25	HTTP client for API calls
`uvicorn`	>=0.30	ASGI server (SSE transport)

4

구성 파일

SOAR MCP 커넥터는 Claude Desktop 또는 Claude Code 구성 파일을 통해 설정합니다.

Claude Desktop Configuration

Location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "soar-autocad": {
      "command": "C:\\soar\\venv\\Scripts\\python.exe",
      "args": ["-m", "soar_autocad_mcp"],
      "env": {
        "SOAR_LICENSE_KEY": "your-license-key-here"
      }
    },
    "soar-excel": {
      "command": "C:\\soar\\venv\\Scripts\\python.exe",
      "args": ["-m", "soar_excel_mcp"]
    }
  }
}
            

Claude Code Configuration

Location: ~/.claude/settings.json

{
  "mcpServers": {
    "soar-autocad": {
      "type": "stdio",
      "command": "C:\\soar\\venv\\Scripts\\python.exe",
      "args": ["-m", "soar_autocad_mcp"]
    }
  }
}
            

5

방화벽 & 네트워크 설정

SOAR MCP 커넥터는 stdio 또는 SSE를 통해 로컬로 통신합니다. 그러나 라이선스 검증 및 AI API 호출에 인터넷 접근이 필요합니다.

Direction	Port	Destination	용도
Outbound	443 (HTTPS)	api.anthropic.com	Claude AI API
Outbound	443 (HTTPS)	api.soar.software	라이선스 검증
Outbound	443 (HTTPS)	github.com	Updates & releases
Local	Dynamic	localhost	MCP stdio/SSE transport

# Windows Firewall - Allow Python outbound (run as Administrator)
netsh advfirewall firewall add rule name="SOAR Python" ^
    dir=out action=allow program="C:\soar\venv\Scripts\python.exe" ^
    enable=yes profile=domain,private

# Verify rule was added / 验证规则
netsh advfirewall firewall show rule name="SOAR Python"
            

🔒 기업 프록시

조직에서 프록시 서버를 사용하는 경우 HTTPS_PROXY 환경 변수를 설정하세요:

set HTTPS_PROXY=http://proxy.company.com:8080

6

Windows Store 고려 사항

⚠️ 중요: Windows Store Python을 사용하지 마세요

Windows Store 버전의 Python은 샌드박스 환경에서 실행되어 다음을 제한합니다:

COM 객체 접근 (AutoCAD, Revit, Excel 등에 필요)
특정 디렉토리에 대한 파일 시스템 쓰기 권한
일부 커넥터에 필요한 레지스트리 접근
긴 파일 경로 지원

사용 중인 Python 확인 방법:

# Check Python location
where python

# If output contains "WindowsApps" = Windows Store version (BAD)
# C:\Users\xxx\AppData\Local\Microsoft\WindowsApps\python.exe

# Should show python.org version (GOOD)
# C:\Python312\python.exe  or  C:\Users\xxx\AppData\Local\Programs\Python\Python312\python.exe
            

Windows Store Python 제거 방법:

# Open Settings > Apps > Installed Apps
# Search for "Python" and uninstall the Microsoft Store version
# Then install from https://python.org/downloads/
            

7

단계별 설치

Step 1: Install Python 3.12 from python.org (check "Add to PATH")
Step 2: Open Command Prompt as Administrator
Step 3: Create installation directory: mkdir C:\soar
Step 4: Create virtual environment: python -m venv C:\soar\venv
Step 5: Activate: C:\soar\venv\Scripts\activate
Step 6: Install connector: pip install soar-autocad-mcp
Step 7: Configure Claude Desktop / Claude Code (see Step 4 above)
Step 8: Launch host application (e.g., AutoCAD)
Step 9: Launch Claude Desktop / Claude Code
Step 10: Test with a simple command: "List all layers in the current drawing"

✅ 확인 체크리스트

설치 후 모든 것이 작동하는지 확인하세요:

python --version returns 3.10+
pip list | findstr soar shows installed connector
Claude가 도구 목록에 MCP 커넥터를 표시
호스트 애플리케이션이 열려 있고 실행 중
테스트 명령이 오류 없이 결과를 반환

8

문제 해결

❌ "MCP server failed to start"

Cause: Python 경로가 올바르지 않거나 가상 환경이 활성화되지 않았습니다.
Fix: 구성 파일의 전체 경로가 실제 Python 실행 파일과 일치하는지 확인하세요. Use where python to find it.

❌ "COM object not found" / "pywintypes.com_error"

Cause: 호스트 애플리케이션이 실행 중이 아니거나 Windows Store Python이 사용되고 있습니다.
Fix: 대상 애플리케이션(AutoCAD, Excel 등)이 열려 있고 실행 중인지 확인하세요. Windows Store 버전을 사용 중이라면 python.org Python으로 전환하세요.

❌ "Connection refused" / "License validation failed"

Cause: 방화벽이 아웃바운드 HTTPS를 차단하거나 프록시가 구성되지 않았습니다.
Fix: 방화벽 규칙을 추가하세요(5단계 참조). 기업 프록시 뒤에 있다면 HTTPS_PROXY environment variable.

❌ "ModuleNotFoundError: No module named 'soar_xxx_mcp'"

Cause: 커넥터가 올바른 가상 환경에 설치되지 않았습니다.
Fix: 먼저 올바른 venv를 활성화한 다음 pip install the connector.

❌ "Permission denied" when accessing files

Cause: Windows UAC 또는 파일 시스템 제한.
Fix: 터미널을 관리자 권한으로 실행하거나 SOAR 작업 디렉토리의 폴더 권한을 조정하세요.

📝 여전히 해결되지 않나요?

GitHub에서 이슈를 열거나 GitHub 오류 로그와 함께, 또는 soardesignjimmy@gmail.com.

기술 가이드

📖 목차