技术指南 - 安装指南

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 / 目录