テクニカルガイド - インストールガイド

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	インターネット必須（HTTPS）	安定したブロードバンド
AI Client	Claude Desktop or Claude Code	Claude Code (latest)
Node.js	18.x	20.x LTS

2

Python環境セットアップ

SOAR MCPコネクタにはPython 3.10以上が必要です。Windows Store版ではなく、python.orgからのインストールを強くお勧めします。

# 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」にチェックを入れてください。

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

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
            

依存パッケージ	バージョン	用途
`mcp`	>=1.0	Model Context Protocol SDK
`pywin32`	>=306	Windows COM自動化
`pydantic`	>=2.0	データバリデーション
`httpx`	>=0.25	API呼び出し用HTTPクライアント
`uvicorn`	>=0.30	ASGIサーバー（SSEトランスポート）

4

設定ファイル

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

ファイアウォール & ネットワーク設定

SOAR MCPコネクタはstdioまたはSSEを介してローカルで通信します。ただし、ライセンス検証とAI API呼び出しにはインターネットアクセスが必要です。

方向	ポート	宛先	用途
Outbound	443 (HTTPS)	api.anthropic.com	Claude AI API
Outbound	443 (HTTPS)	api.soar.software	ライセンス認証
Outbound	443 (HTTPS)	github.com	アップデート & リリース
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の確認方法 / 如何检查你的 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

ステップバイステップインストール

ステップ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）
ステップ9：Claude Desktop / Claude Codeを起動
ステップ10：簡単なコマンドでテスト：「現在の図面のすべてのレイヤーを一覧表示」

✅ 確認チェックリスト

インストール後、すべてが正常に動作していることを確認してください：

python --version が3.10以上を返す
pip list | findstr soar がインストール済みコネクタを表示
ClaudeのツールリストにMCPコネクタが表示される
ホストアプリケーションが起動して実行中
テストコマンドがエラーなく結果を返す

8

トラブルシューティング

❌ "MCP server failed to start"

原因：Pythonパスが正しくないか、仮想環境がアクティベートされていません。
修正：設定ファイルのフルパスが実際のPython実行ファイルと一致していることを確認してください。where pythonで確認できます。

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

原因：ホストアプリケーションが起動していないか、Windows Store版Pythonが使用されています。
修正：対象アプリケーション（AutoCAD、Excelなど）が開いて実行中であることを確認してください。Windows Store版を使用している場合はpython.org版に切り替えてください。

❌ "Connection refused" / "License validation failed"

原因：ファイアウォールがアウトバウンドHTTPSをブロック、またはプロキシ未設定。
修正：ファイアウォールルールを追加（ステップ5参照）。企業プロキシの背後にいる場合はHTTPS_PROXY環境変数を設定。

❌ "ModuleNotFoundError: No module named 'soar_xxx_mcp'"

原因：正しい仮想環境にコネクタがインストールされていません。
修正：まず正しいvenvをアクティベートし、その後pip installでコネクタをインストールしてください。

❌ "Permission denied" when accessing files

原因：Windows UACまたはファイルシステムの制限。
修正：管理者としてターミナルを実行するか、SOAR作業ディレクトリのフォルダ権限を調整してください。

📝 まだ解決しませんか？

GitHubでエラーログとともにIssueを作成するか、こちらまでご連絡ください： soardesignjimmy@gmail.com.

Tech Guide

📖 目次