# imagery.vision MCP-Server installieren — Anleitung für KI-Agenten

Diese Datei richtet sich an einen KI-Agenten (Claude Code, Codex, Cursor, VS Code Copilot,
Windsurf …), den ein Mensch gebeten hat, die imagery.vision-MCP-Verbindung auf seinem
Rechner einzurichten. Arbeite die Schritte der Reihe nach ab. Antworte dem Menschen in
seiner Sprache, kurz und ohne Fachjargon — die Nutzer sind meist Architektinnen und
Architekten, keine Entwickler.

Menschliche Anleitung mit Hintergrund: https://docs.imagery.vision/editor/mcp/

## Was installiert wird

`imagery-mcp` ist ein lokaler stdio-MCP-Server. Er verbindet den MCP-Client mit dem
geöffneten, eingeloggten imagery.vision-Tab im Browser (Chrome oder Edge) über
`localhost`. Es gibt kein Konto-Login im Server und keine Netzwerkfreigabe nach außen.

- **Paket (aktuelle Version):** `https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz`
  Es liegt nicht in der npm-Registry — immer genau diese URL verwenden, nie `imagery-mcp`
  ohne URL und nie eine ältere Version.
- **Servername in der Konfiguration:** `imagery`
- **Umgebungsvariable:** `IMAGERY_MCP_TOKEN` = Kopplungs-Code des Nutzers
- **Start:** `npx -y <Paket-URL>`

## Regeln

1. **Kopplungs-Code.** Ohne ihn verbindet sich nichts. Der Nutzer findet ihn in
   imagery.vision auf dem Node **MCP-Verbindung** (Doppelklick auf den Canvas → „MCP“
   suchen). Steht er schon in der Nachricht des Nutzers, nutze ihn. Sonst bitte den Nutzer,
   ihn zu nennen — oder trage den Platzhalter `DEIN-KOPPLUNGS-CODE` ein und sag am Ende
   genau, in welcher Datei er ihn ersetzen muss. Gib den Code in deinen Antworten nicht
   wieder aus. Hat der Nutzer im Node **Neuen Code erzeugen** geklickt, gilt der alte
   Code nicht mehr — dann den Eintrag mit dem neuen Code ersetzen.
2. **Nicht in Git.** Schreib den Code nie in eine Datei, die in einem Git-Repository
   eingecheckt würde (z. B. `.vscode/mcp.json` oder `.cursor/mcp.json` eines Projekts).
   Bevorzuge immer die nutzerweite (globale) Konfiguration.
3. **Bestehende Konfiguration erhalten.** JSON-/TOML-Dateien nie überschreiben, sondern
   den Eintrag `imagery` einfügen bzw. ersetzen und alle anderen Einträge unverändert
   lassen. Vor dem Ändern eine Sicherungskopie (`<datei>.bak`) anlegen. Danach prüfen,
   dass die Datei noch gültiges JSON/TOML ist.
4. **Keine Doppelten.** Gibt es schon einen Eintrag, der `imagery-mcp` startet (unter
   `imagery`, `imagery_vision` o. Ä.), ersetze ihn statt einen zweiten anzulegen — außer
   es ist die Claude-Desktop-Erweiterung (siehe unten).
5. **Nur einrichten, nichts ausführen.** Keine imagery-Werkzeuge aufrufen, keine Workflows
   starten — jede Generierung kostet den Nutzer Credits.

## Schritt 1: Voraussetzungen prüfen

- `node --version` muss **v20 oder neuer** zeigen. Fehlt Node oder ist es älter: abbrechen
  und den Nutzer bitten, die LTS-Version von https://nodejs.org zu installieren. Danach
  von vorn beginnen. (Ausnahme: Claude-Desktop-Erweiterung, siehe unten — die braucht
  kein Node.)
- Betriebssystem feststellen (macOS, Windows, Linux). Unter Windows gelten die
  Windows-Hinweise unten.

## Schritt 2: Client bestimmen

Richte die Verbindung für das Programm ein, in dem du gerade läufst. Wenn der Nutzer ein
anderes Programm nennt, nimm das. Bei Unklarheit fragen.

### Claude Code (Terminal oder Code-Tab der Claude-Desktop-App)

Nutzerweit eintragen:

```bash
claude mcp add imagery --scope user -e IMAGERY_MCP_TOKEN=<CODE> -- npx -y https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz
```

Windows (PowerShell):

```powershell
claude mcp add imagery --scope user -e IMAGERY_MCP_TOKEN=<CODE> -- cmd /c npx -y https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz
```

Existiert `imagery` schon: vorher `claude mcp remove imagery --scope user`.

Ist der Befehl `claude` nicht im Suchpfad (häufig im Code-Tab der Desktop-App): trage den
Server stattdessen in `~/.claude.json` ein — im **obersten** Objekt unter `mcpServers`
(nicht unter `projects`). Die Datei ist groß und enthält andere Einstellungen: per Skript
einlesen, nur den Schlüssel ergänzen, zurückschreiben.

```json
"imagery": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz"],
  "env": { "IMAGERY_MCP_TOKEN": "<CODE>" }
}
```

Prüfen: `claude mcp list` zeigt `imagery` (falls `claude` verfügbar).

**Alternative: Plugin** (nur wenn der Nutzer es so will; unter Windows noch nicht geprüft,
dort den Eintrag oben nehmen). Nicht zusätzlich zum Eintrag oben — sonst erscheint jedes
Werkzeug doppelt; einen bestehenden Eintrag vorher mit `claude mcp remove imagery --scope user`
entfernen:

```bash
claude plugin marketplace add sbauer-hash/imagery-claude-plugins
claude plugin install imagery@imagery-claude-plugins --config pairing_token=<CODE>
```

### Codex (CLI, IDE-Erweiterung und ChatGPT-Desktop-App)

```bash
codex mcp add imagery --env IMAGERY_MCP_TOKEN=<CODE> -- npx -y https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz
```

Ohne `codex`-Befehl: in `~/.codex/config.toml` ergänzen (bzw. den bestehenden Abschnitt
ersetzen):

```toml
[mcp_servers.imagery]
command = "npx"
args = ["-y", "https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz"]
env = { IMAGERY_MCP_TOKEN = "<CODE>" }
```

Prüfen: `codex mcp list`. Die ChatGPT-Desktop-App liest dieselbe Konfiguration (noch
nicht verifiziert — sag dem Nutzer, dass er sich meldet, wenn sie dort nicht erscheint).
ChatGPT im Browser kann keine lokalen Server starten.

### Cursor

Global in `~/.cursor/mcp.json` (Windows: `%USERPROFILE%\.cursor\mcp.json`), unter
`mcpServers`:

```json
{
  "mcpServers": {
    "imagery": {
      "command": "npx",
      "args": ["-y", "https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz"],
      "env": { "IMAGERY_MCP_TOKEN": "<CODE>" }
    }
  }
}
```

### Windsurf

Wie Cursor, Datei `~/.codeium/windsurf/mcp_config.json`.

### VS Code (GitHub Copilot)

Nutzerweit über die Kommandozeile:

```bash
code --add-mcp '{"name":"imagery","type":"stdio","command":"npx","args":["-y","https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz"],"env":{"IMAGERY_MCP_TOKEN":"<CODE>"}}'
```

Ohne `code`-Befehl (und unter Windows, wo die Anführungszeichen in PowerShell
verloren gehen): den Nutzer bitten, in VS Code **Befehlspalette → „MCP: Open User
Configuration“** zu öffnen, und den Eintrag dort unter `servers` (nicht `mcpServers`)
ergänzen:

```json
{
  "servers": {
    "imagery": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz"],
      "env": { "IMAGERY_MCP_TOKEN": "<CODE>" }
    }
  }
}
```

Keine `mcp.json` im Projektordner anlegen (Regel 2).

### Claude Desktop (Chat)

Für den Chat in Claude Desktop ist die **Erweiterung** der empfohlene Weg — sie braucht
kein Node.js. Das kann der Nutzer nur selbst: Sag ihm, er soll
https://docs.imagery.vision/downloads/imagery-mcp.mcpb herunterladen, per Doppelklick
installieren, im Feld **Kopplungs-Code** seinen Code eintragen und unter
**Einstellungen → Erweiterungen** prüfen, dass „imagery.vision“ aktiviert ist.

Nur wenn der Nutzer ausdrücklich keine Erweiterung will: Eintrag wie bei Cursor in
`claude_desktop_config.json` unter `mcpServers` — macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`, Windows:
`%APPDATA%\Claude\claude_desktop_config.json`. Nie beides zusammen (sonst erscheint jedes
Werkzeug doppelt). Danach Claude Desktop komplett beenden und neu starten.

Die Erweiterung gilt nur für den Chat. Ein zusätzlicher Claude-Code-Eintrag für den
Code-Tab ist erlaubt und stört nicht.

### Ohne KI-App (nur Rhino/Revit-Anbindung)

Seit 0.13.0 richtet jeder der Wege oben beim ersten Start selbst einen Hintergrunddienst ein
und hält ihn aktuell — **führe `install` nicht zusätzlich aus**, wenn du gerade einen Client
eingerichtet hast. Wer den Dienst nicht will, setzt `IMAGERY_MCP_SERVICE=off` in die `env`
des Eintrags (bei der Claude-Desktop-Erweiterung: Option „Hintergrunddienst“).

Nur wenn der Nutzer gar kein KI-Programm hat und imagery.vision mit Rhino oder Revit
verbinden will:

```bash
npx -y https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz install --token <CODE>
```

Das richtet einen Hintergrunddienst ein (macOS/Windows), der bei jeder Anmeldung startet.
Prüfen mit `… status`, entfernen mit `… uninstall` (gleiche Zeile, letztes Wort ersetzt).
Unter Windows in PowerShell `npx.cmd` statt `npx` schreiben (siehe Windows-Hinweise).

## Windows-Hinweise

- Startet der Server in einem JSON-konfigurierten Client nicht, `npx` über `cmd` starten:
  `"command": "cmd"`, `"args": ["/c", "npx", "-y", "<Paket-URL>"]`.
- PowerShell-Befehle in PowerShell ausführen, nicht in `cmd.exe`.
- Meldet PowerShell „npx.ps1 kann nicht geladen werden“, blockiert die
  Ausführungsrichtlinie das Skript: denselben Befehl mit `npx.cmd` statt `npx` ausführen.
  Die Richtlinie selbst nicht ändern.

## Schritt 3: Testen, ob das Paket lädt (optional)

```bash
npx -y https://docs.imagery.vision/downloads/imagery-mcp-0.13.0.tgz status
```

Der Befehl lädt das Paket einmal in den npx-Cache und zeigt drei Zeilen Zustand.
„Hintergrunddienst: nicht installiert“ ist hier normal — der Dienst gehört nur zum Weg
„Ohne KI-App“. Wichtig ist nur, dass der Befehl ohne Fehler durchläuft.

## Schritt 4: Dem Nutzer sagen, was noch zu tun ist

Fasse am Ende in wenigen Sätzen zusammen, ohne den Kopplungs-Code zu wiederholen:

1. Welche Datei bzw. welcher Befehl geändert wurde.
2. Falls ein Platzhalter eingetragen wurde: wo der Kopplungs-Code noch eingesetzt werden muss.
3. **Programm neu starten** (bzw. neue Session/neuen Chat beginnen), damit es den Server lädt.
4. imagery.vision in **Chrome oder Edge** öffnen, anmelden und oben rechts auf den Chip
   **MCP** klicken. Beim ersten Mal fragt der Browser, ob die Seite auf Programme dieses
   Rechners zugreifen darf — erlauben. Der Punkt im Chip wird grün, sobald alles steht.
5. Danach kann der Nutzer im KI-Programm z. B. schreiben: „Bau mir in imagery.vision einen
   Workflow, der aus meinem Rhino-Screenshot ein fotorealistisches Rendering macht.“

## Wenn etwas nicht klappt

- **Chip bleibt orange:** Der Server läuft nicht — Programm neu starten, Konfiguration
  prüfen, Node-Version prüfen.
- **„Kopplungs-Code passt nicht“ / keine Verbindung:** Der Code gilt pro Browserprofil.
  Den Code aus genau dem Browser verwenden, in dem imagery.vision geöffnet ist.
- **Safari oder Firefox:** Funktioniert nicht, Chrome oder Edge nutzen.
- Weitere Hilfe: https://docs.imagery.vision/editor/mcp/#wenn-etwas-nicht-klappt