Technischer Leitfaden

1

Systemanforderungen

Komponente	Minimum	Empfohlen
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 frei	2 GB+ frei
CPU	4 Kerne	8+ Kerne
Network	Internet erforderlich (HTTPS)	Stabiles Breitband
AI Client	Claude Desktop oder Claude Code	Claude Code (neueste Version)
Node.js	18.x	20.x LTS

2

Python-Umgebung einrichten

SOAR MCP-Konnektoren erfordern Python 3.10 oder höher. Wir empfehlen dringend, Python von python.org zu installieren, anstatt die Windows Store-Version zu verwenden.

# Python-Installation überprüfen
python --version
# Erwartete Ausgabe: Python 3.12.x

# pip verfügbar prüfen
pip --version

# Virtuelle Umgebung erstellen (empfohlen)
python -m venv C:\soar\venv
C:\soar\venv\Scripts\activate

# Aktivierung überprüfen
where python
# Sollte anzeigen: C:\soar\venv\Scripts\python.exe
            

⚠️ Windows Store Python

Die Windows Store-Version von Python hat bekannte Probleme mit Dateipfad-Berechtigungen und COM-Automatisierung. Verwenden Sie immer den python.org-Installer und stellen Sie sicher, dass "Add Python to PATH" während der Installation aktiviert ist.

3

Abhängigkeiten

Jeder SOAR MCP-Konnektor hat eigene Abhängigkeiten. Installieren Sie diese mit pip nach Aktivierung Ihrer virtuellen Umgebung.

# SOAR MCP-Konnektor installieren (Beispiel: AutoCAD)
pip install soar-autocad-mcp

# Oder von GitHub-Release installieren
pip install https://github.com/soarmcpsoftware/soar-autocad-mcp/releases/latest/download/soar-autocad-mcp.tar.gz

# Häufige Abhängigkeiten werden automatisch installiert:
#   - mcp (Model Context Protocol SDK)
#   - pywin32 (Windows COM-Automatisierung)
#   - pydantic (Datenvalidierung)
#   - httpx (HTTP-Client)

# Installation überprüfen
pip list | findstr soar
            

Abhängigkeit	Version	Zweck
`mcp`	>=1.0	Model Context Protocol SDK
`pywin32`	>=306	Windows COM-Automatisierung
`pydantic`	>=2.0	Datenvalidierung
`httpx`	>=0.25	HTTP-Client für API-Aufrufe
`uvicorn`	>=0.30	ASGI-Server (SSE-Transport)

4

Konfigurationsdateien

SOAR MCP-Konnektoren werden über die Claude Desktop- oder Claude Code-Konfigurationsdatei eingerichtet.

Claude Desktop-Konfiguration

Speicherort: %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-Konfiguration

Speicherort: ~/.claude/settings.json

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

5

Firewall & Netzwerkeinstellungen

SOAR MCP-Konnektoren kommunizieren lokal über stdio oder SSE. Sie benötigen jedoch Internetzugang für Lizenzvalidierung und KI-API-Aufrufe.

Richtung	Port	Ziel	Zweck
Ausgehend	443 (HTTPS)	api.anthropic.com	Claude KI-API
Ausgehend	443 (HTTPS)	api.soar.software	Lizenzvalidierung
Ausgehend	443 (HTTPS)	github.com	Updates & Releases
Lokal	Dynamic	localhost	MCP stdio/SSE-Transport

# Windows Firewall - Python ausgehend zulassen (als Administrator ausführen)
netsh advfirewall firewall add rule name="SOAR Python" ^
    dir=out action=allow program="C:\soar\venv\Scripts\python.exe" ^
    enable=yes profile=domain,private

# Regel überprüfen
netsh advfirewall firewall show rule name="SOAR Python"
            

🔒 Unternehmens-Proxy

Wenn Ihre Organisation einen Proxy-Server verwendet, setzen Sie die Umgebungsvariable HTTPS_PROXY:

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

6

Hinweise zum Windows Store

⚠️ Wichtig: Verwenden Sie NICHT Windows Store Python

Die Windows Store-Version von Python läuft in einer Sandbox-Umgebung, die Folgendes einschränkt:

COM-Objektzugriff (erforderlich für AutoCAD, Revit, Excel usw.)
Dateisystem-Schreibberechtigungen für bestimmte Verzeichnisse
Registrierungszugriff, den einige Konnektoren benötigen
Unterstützung langer Dateipfade

So prüfen Sie, welches Python Sie haben:

# Python-Speicherort prüfen
where python

# Falls Ausgabe "WindowsApps" enthält = Windows Store Version (SCHLECHT)
# C:\Users\xxx\AppData\Local\Microsoft\WindowsApps\python.exe

# Sollte python.org-Version anzeigen (GUT)
# C:\Python312\python.exe  or  C:\Users\xxx\AppData\Local\Programs\Python\Python312\python.exe
            

Windows Store Python entfernen:

# Öffnen Sie Einstellungen > Apps > Installierte Apps
# Suchen Sie "Python" und deinstallieren Sie die Microsoft Store-Version
# Dann installieren Sie von https://python.org/downloads/
            

7

Schritt-für-Schritt-Installation

Schritt 1: Installieren Sie Python 3.12 von python.org (aktivieren Sie "Add to PATH")
Schritt 2: Öffnen Sie die Eingabeaufforderung als Administrator
Schritt 3: Installationsverzeichnis erstellen: mkdir C:\soar
Schritt 4: Virtuelle Umgebung erstellen: python -m venv C:\soar\venv
Schritt 5: Aktivieren: C:\soar\venv\Scripts\activate
Schritt 6: Konnektor installieren: pip install soar-autocad-mcp
Schritt 7: Claude Desktop / Claude Code konfigurieren (siehe Schritt 4 oben)
Schritt 8: Hostanwendung starten (z.B. AutoCAD)
Schritt 9: Claude Desktop / Claude Code starten
Schritt 10: Mit einem einfachen Befehl testen: "Liste alle Layer in der aktuellen Zeichnung auf"

✅ Prüfliste zur Verifizierung

Nach der Installation überprüfen Sie, ob alles funktioniert:

python --version gibt 3.10+ zurück
pip list | findstr soar zeigt installierten Konnektor
Claude zeigt den MCP-Konnektor in seiner Werkzeugliste
Hostanwendung ist geöffnet und läuft
Ein Testbefehl liefert Ergebnisse ohne Fehler

8

Fehlerbehebung

❌ "MCP server failed to start"

Ursache: Python-Pfad falsch oder virtuelle Umgebung nicht aktiviert.
Lösung: Überprüfen Sie, ob der vollständige Pfad in Ihrer Konfigurationsdatei mit Ihrer tatsächlichen Python-Programmdatei übereinstimmt. Verwenden Sie where python um ihn zu finden.

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

Ursache: Hostanwendung läuft nicht oder Windows Store Python wird verwendet.
Lösung: Stellen Sie sicher, dass die Zielanwendung (AutoCAD, Excel usw.) geöffnet und aktiv ist. Wechseln Sie zu python.org Python, falls Sie die Windows Store-Version verwenden.

❌ "Connection refused" / "License validation failed"

Ursache: Firewall blockiert ausgehende HTTPS-Verbindungen oder Proxy nicht konfiguriert.
Lösung: Fügen Sie Firewall-Regeln hinzu (siehe Schritt 5). Bei Unternehmens-Proxy setzen Sie die Umgebungsvariable HTTPS_PROXY.

❌ "ModuleNotFoundError: No module named 'soar_xxx_mcp'"

Ursache: Konnektor nicht in der richtigen virtuellen Umgebung installiert.
Lösung: Aktivieren Sie zuerst die richtige venv, dann installieren Sie den Konnektor mit pip install.

❌ "Permission denied" when accessing files

Ursache: Windows UAC oder Dateisystem-Einschränkungen.
Lösung: Führen Sie das Terminal als Administrator aus oder passen Sie die Ordnerberechtigungen für das SOAR-Arbeitsverzeichnis an.

📝 Immer noch Probleme?

Eröffnen Sie ein Issue auf GitHub mit Ihrem Fehlerprotokoll oder kontaktieren Sie uns unter soardesignjimmy@gmail.com.

📖 Inhaltsverzeichnis