技術指南 - 安裝指南

1

系統需求系统要求

Component / 组件	Minimum / 最低	Recommended / 推荐
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 Environment SetupPython 环境配置

SOAR MCP 連接器需要 Python 3.10 或更高版本。我們強烈建議從 python.org 安裝 Python，而非 Windows 商店版本。

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

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

# Create a virtual environment (建議) / 创建虚拟环境（推荐）
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 商店版 Python

Windows 商店版 Python 在檔案路徑權限和 COM 自動化方面有已知問題。請始終使用 python.org 安裝程式，並確保在安裝過程中勾選「Add Python to PATH」。

Windows 商店版 Python 在文件路径权限和 COM 自动化方面有已知问题。请始终使用 python.org 安装程序。

3

Dependencies依赖项

每個 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
            

相依套件	版本	Purpose / 用途
`mcp`	>=1.0	Model Context Protocol SDK
`pywin32`	>=306	Windows COM automation / Windows COM 自动化
`pydantic`	>=2.0	資料驗證
`httpx`	>=0.25	API 呼叫的 HTTP 用戶端
`uvicorn`	>=0.30	ASGI 伺服器（SSE 傳輸）

4

Configuration Files配置文件

SOAR MCP 連接器透過 Claude Desktop 或 Claude Code 設定檔進行配置。

Claude Desktop 設定

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 設定

Location: ~/.claude/settings.json

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

5

Firewall & Network Settings防火墙和网络设置

SOAR MCP 連接器透過 stdio 或 SSE 進行本地通訊。但它們需要網路連線進行授權驗證和 AI API 呼叫。

方向	連接埠	目標	Purpose / 用途
出站	443 (HTTPS)	api.anthropic.com	Claude AI API
出站	443 (HTTPS)	api.soar.software	License validation / 许可证验证
出站	443 (HTTPS)	github.com	更新與版本
本地	動態	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"
            

🔒 Corporate Proxy / 企业代理

如果貴組織使用代理伺服器，請設定 HTTPS_PROXY 環境變數：

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

6

Windows 商店版注意事項Windows 商店版注意事项

⚠️ 重要：請勿使用 Windows 商店版 Python

Windows 商店版 Python 在沙盒環境中運行，限制了：

COM 物件存取（AutoCAD、Revit、Excel 等所需）
對特定目錄的檔案系統寫入權限
某些連接器所需的登錄檔存取
長檔案路徑支援

如何檢查您的 Python 版本：

# Check Python location
where python

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

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

移除 Windows 商店版 Python：

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

7

Step-by-Step Installation分步安装指南

步驟 1: 從 python.org 安裝 Python 3.12（勾選「Add to PATH」）
步驟 2: 以管理員身份開啟命令提示字元
步驟 3: 建立安裝目錄： mkdir C:\soar
步驟 4: 建立虛擬環境： python -m venv C:\soar\venv
步驟 5: 啟動： C:\soar\venv\Scripts\activate
步驟 6: 安裝連接器： pip install soar-autocad-mcp
步驟 7: 配置 Claude Desktop / Claude Code（請參閱上方步驟 4）
步驟 8: 啟動宿主應用程式（例如 AutoCAD）
Step 9: 啟動 Claude Desktop / Claude Code
步驟 10: 使用簡單指令測試：「列出當前圖面中的所有圖層」

✅ Verification Checklist / 验证清单

安裝完成後，請驗證一切正常：

python --version 回傳 3.10+
pip list | findstr soar 顯示已安裝的連接器
Claude 在其工具列表中顯示 MCP 連接器
宿主應用程式已開啟並正在運行
測試指令回傳結果且無錯誤

8

Troubleshooting故障排除

❌ "MCP server failed to start"

原因： Python 路徑不正確或虛擬環境未啟動。
修復： 驗證設定檔中的完整路徑與實際 Python 執行檔是否相符。使用 where python 找到它。

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

原因： 宿主應用程式未運行，或正在使用 Windows 商店版 Python。
修復： 確保目標應用程式（AutoCAD、Excel 等）已開啟並正在運行。如果使用 Windows 商店版本，請切換到 python.org Python。

❌ "Connection refused" / "License validation failed"

原因： 防火牆阻擋出站 HTTPS，或代理未配置。
修復： 新增防火牆規則（請參閱步驟 5）。如果在企業代理後面，請設定 HTTPS_PROXY environment variable.

❌ "ModuleNotFoundError: No module named 'soar_xxx_mcp'"

原因： 連接器未安裝在正確的虛擬環境中。
修復： 先啟動正確的 venv，然後 pip install 連接器。

❌ "Permission denied" when accessing files

原因： Windows UAC 或檔案系統限制。
修復： 以管理員身份執行終端機，或調整 SOAR 工作目錄的資料夾權限。

📝 Still stuck? / 仍然有问题？

在 GitHub 提交 issue 並附上錯誤日誌，或聯絡我們： soardesignjimmy@gmail.com.

Tech Guide

📖 Table of Contents / 目录