Tech Guide

1

System Requirements系统要求

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 connectors require Python 3.10 or higher. We strongly recommend installing Python from python.org rather than the Windows Store version.

# 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 商店版 Python

The Windows Store version of Python has known issues with file path permissions and COM automation. Always use the python.org installer and ensure "Add Python to PATH" is checked during installation.

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

3

Dependencies依赖项

Each SOAR MCP connector has its own dependencies. Install them using pip after activating your virtual environment.

# 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	Purpose / 用途
`mcp`	>=1.0	Model Context Protocol SDK
`pywin32`	>=306	Windows COM automation / Windows COM 自动化
`pydantic`	>=2.0	Data validation
`httpx`	>=0.25	HTTP client for API calls
`uvicorn`	>=0.30	ASGI server (SSE transport)

4

Configuration Files配置文件

SOAR MCP connectors are configured through the Claude Desktop or Claude Code configuration file.

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

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

SOAR MCP connectors communicate locally via stdio or SSE. However, they require internet access for license validation and AI API calls.

Direction	Port	Destination	Purpose / 用途
Outbound	443 (HTTPS)	api.anthropic.com	Claude AI API
Outbound	443 (HTTPS)	api.soar.software	License validation / 许可证验证
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"
            

🔒 Corporate Proxy / 企业代理

If your organization uses a proxy server, set the HTTPS_PROXY environment variable:

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

6

Windows Store ConsiderationsWindows 商店版注意事项

⚠️ Critical: Do NOT Use Windows Store Python

The Windows Store version of Python runs in a sandboxed environment that restricts:

COM object access (required for AutoCAD, Revit, Excel, etc.)
File system write permissions to certain directories
Registry access needed by some connectors
Long file path support

How to check which Python you have / 如何检查你的 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
            

To remove Windows Store Python / 卸载 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分步安装指南

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"

✅ Verification Checklist / 验证清单

After installation, verify everything is working:

python --version returns 3.10+
pip list | findstr soar shows installed connector
Claude shows the MCP connector in its tools list
Host application is open and running
A test command returns results without errors

8

Troubleshooting故障排除

❌ "MCP server failed to start"

Cause: Python path incorrect or virtual environment not activated.
Fix: Verify the full path in your config file matches your actual Python executable. Use where python to find it.

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

Cause: Host application not running, or Windows Store Python is being used.
Fix: Ensure the target application (AutoCAD, Excel, etc.) is open and running. Switch to python.org Python if using Windows Store version.

❌ "Connection refused" / "License validation failed"

Cause: Firewall blocking outbound HTTPS, or proxy not configured.
Fix: Add firewall rules (see Step 5). If behind a corporate proxy, set HTTPS_PROXY environment variable.

❌ "ModuleNotFoundError: No module named 'soar_xxx_mcp'"

Cause: Connector not installed in the correct virtual environment.
Fix: Activate the correct venv first, then pip install the connector.

❌ "Permission denied" when accessing files

Cause: Windows UAC or file system restrictions.
Fix: Run the terminal as Administrator, or adjust folder permissions for the SOAR working directory.

📝 Still stuck? / 仍然有问题？

Open an issue on GitHub with your error log, or contact us at soardesignjimmy@gmail.com.

📖 Table of Contents / 目录