# Per MCP verbinden

Verbinden Sie Claude Desktop, Claude Code, Cursor, Codex oder einen anderen MCP-Client mit den lokalen Projektwerkzeugen von Oleafly.

Oleafly kann als MCP-Server (Model Context Protocol) fungieren. MCP-Clients wie Claude Desktop, Claude Code, Cursor, Codex und Grok CLI können ein Oleafly-Projekt lesen, bearbeiten, durchsuchen und kompilieren. Sie brauchen in Oleafly keinen Schlüssel eines KI-Anbieters, weil der Client das Modell mitbringt.

Das ist die richtige Option, wenn Sie bereits ein Claude-Abonnement (oder ein ähnliches) haben und wollen, dass diese Chat-App Oleafly steuert, ohne einen API-Schlüssel in die [Einstellungen](/docs/ai-setup/) einzufügen.

## Aktivieren

1. Öffnen Sie **Einstellungen → Integrationen → Oleafly MCP**.
2. Schalten Sie **MCP-Server aktivieren** ein.

Der Server läuft nur, solange der Oleafly-Prozess geöffnet ist. Er lauscht nur auf `127.0.0.1`, nie in Ihrem lokalen Netzwerk. Das Schließen des Projektfensters beendet den Server nicht. MCP abschalten oder Oleafly beenden schon.

Oleafly bevorzugt den Port `5323` (`http://127.0.0.1:5323/mcp`). Ist er nicht verfügbar, bindet der Server automatisch einen anderen freien lokalen Port und speichert ihn für den nächsten Start. Die Einstellungen zeigen die aktive URL. Ihre Neustart-Schaltfläche nutzt den aktuellen Port wieder, wenn möglich, oder wählt einen anderen freien.

## Verbinden Sie Ihren Client

:::tip[Kein Token zu kopieren]
Der `oleafly`-Befehl hat einen eigenen MCP-Server, der über Standardeingabe und Standardausgabe spricht. Er findet die laufende App und ihr Token von selbst, sodass Sie weder eine URL noch ein Token kopieren müssen und Node.js nicht brauchen. `oleafly mcp config --client claude-desktop` gibt die Einrichtung aus; die Client-Namen sind `claude-code`, `claude-desktop`, `codex`, `cursor` und `gemini`. Siehe [Befehlszeilenwerkzeug](/docs/cli/#connect-an-agent-over-mcp).
:::

Die Einstellungen zeigen fertige Snippets zum Kopieren für gängige Clients. Kopieren Sie die aktive URL, weil der gewählte Port vom `5323` abweichen kann, und ersetzen Sie dann `<token>` durch das Bearer-Token aus den Einstellungen (Anzeigen / Kopieren).

### Claude Code

```bash
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"
```

### Claude Desktop

Fügen Sie dies zu `claude_desktop_config.json` hinzu (stdio-Brücke über `mcp-remote`, weil Desktop stdio bevorzugt):

```json
{
  "mcpServers": {
    "oleafly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://127.0.0.1:5323/mcp",
        "--header",
        "Authorization: Bearer <token>",
        "--transport",
        "http-only"
      ]
    }
  }
}
```

### Claude-Desktop-Erweiterung

Jede Version enthält `oleafly.mcpb`, eine Erweiterung für Claude Desktop. Sie brauchen dann weder die Konfigurationsdatei noch das Token. Laden Sie die Datei aus der [neuesten Version](https://github.com/Oleafly/Oleafly/releases/latest) herunter und öffnen Sie sie mit Claude Desktop, um sie zu installieren.

Die Erweiterung startet den `oleafly`-Befehl, der mit der App kommt, und arbeitet mit dem Projekt, das in Oleafly geöffnet ist. Lassen Sie Oleafly also mit eingeschaltetem MCP-Server laufen. Findet Claude Desktop den Befehl nicht, wählen Sie ihn in den Einstellungen der Erweiterung aus: `oleafly-cli` in `Oleafly.app/Contents/MacOS` unter macOS oder `oleafly-cli.exe` in `%LOCALAPPDATA%\Oleafly` unter Windows.

Die MCP Registry führt dieselbe Erweiterung als `io.github.Oleafly/oleafly`.

### Cursor / VS Code

In `.cursor/mcp.json` (oder der MCP-Konfiguration Ihres Clients):

```json
{
  "mcpServers": {
    "oleafly": {
      "url": "http://127.0.0.1:5323/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

### Grok CLI

In `~/.grok/config.toml`:

```toml
[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }
```

### Codex CLI

Verwenden Sie das **Codex CLI**-Snippet in den Oleafly-Einstellungen, das eine stdio-Brücke zum laufenden Server bereitstellt. Fügen Sie den Eintrag zu Ihrer Codex-Konfiguration hinzu und verwenden Sie die aktive URL und das Token, die Oleafly anzeigt:

```toml title="~/.codex/config.toml"
[mcp_servers.oleafly]
command = "npx"
args = [
  "-y",
  "mcp-remote@latest",
  "http://127.0.0.1:5323/mcp",
  "--header",
  "Authorization: Bearer <token>",
  "--transport",
  "http-only"
]
```

Die Brücke benötigt Node.js und `npx`. Starten Sie den Client nach einer Änderung seiner Konfiguration neu oder verbinden Sie ihn erneut.

Die Datei `mcp.json` neben Ihren Oleafly-Daten (in den Einstellungen angezeigt) enthält dieselbe URL und dasselbe Token, wenn Sie die Einrichtung lieber per Skript erledigen. Sie wird nur geschrieben, während der Server läuft (Modus `0600` unter Unix), und gelöscht, wenn der Server stoppt. Behandeln Sie sie wie jedes andere lokale Geheimnis.

## Was die Werkzeuge können

Die meisten MCP-Werkzeuge teilen ihre Namen und Schemas mit dem Assistenten in der App. Die Werkzeuge zum Auffinden und Auswählen von Projekten stellt das Desktop-Backend bereit.

Werkzeuge richten sich auf das Projekt, das in der App geöffnet ist, wenn eines verfügbar ist. Ist ein Fenster verbunden, verwenden Sie `list_projects` und `open_project`, um ein anderes Projekt auszuwählen.

Nach dem Schließen des letzten Fensters bleiben `read_file`, `list_files` und `search_project` im Backend verfügbar. Native Schreibzugriffe, Ersetzungen, Neuanlagen und Umbenennungen bleiben ebenfalls verfügbar, wenn die Freigaberichtlinie sie zulässt. Diese Werkzeuge nutzen nur das zuletzt von der App gemeldete Projekt und lehnen den Aufruf ab, wenn dieses Projekt nicht mehr gültig ist. Sie raten nie anhand anderer Projekte in der Bibliothek. Status, Projektauswahl, Löschen, Kompilieren, Logs, PDF-Prüfung, Designwechsel und Abbildungswerkzeuge erfordern ein verbundenes Fenster.

### Orientierung

| Werkzeug | Was es tut |
|---|---|
| `get_status` | Oleafly-Version, geöffnetes Projekt, dessen Dokument-Engine, Hauptdokument, letzter Kompilierstatus, und warum die letzte Kompilierung scheiterte oder nicht laufen konnte |
| `list_projects` | Projekte mit IDs, Namen, Engines, Arten, Hauptdokumenten, Zeitstempeln, Farben, Vorschauzustand und Exporthistorie |
| `open_project` | Ein Projekt anhand der ID öffnen, sodass andere Werkzeuge es ansprechen |
| `list_files` | Dateibaum des Projekts |
| `project_map` | Gliederung, Labels, Zitationen, Makros, Eingabegraph, offene Verweise |
| `search_project` | Text im aktuellen Projekt durchsuchen |

### Lesen

| Werkzeug | Was es tut |
|---|---|
| `read_file` | Eine Projektdatei lesen |
| `get_log` | Letztes Kompilier-Log |
| `get_pdf_text` | Aus dem kompilierten PDF extrahierter Text |
| `verify_pdf_pages` | Gerenderte PDF-Seiten auf Layoutprobleme prüfen, anhand von Seitenbildern oder Seitentext |

`get_pdf_text` und `verify_pdf_pages` lesen das letzte PDF, das Oleafly hat. Ist die letzte Kompilierung gescheitert oder konnte nicht laufen, sagt ihr Ergebnis, dass das PDF veraltet ist, und warum, weil es aus einer früheren Kompilierung stammt oder ein Teilergebnis der gescheiterten Kompilierung ist. `get_log` sagt dasselbe, wenn die letzte Kompilierung nicht laufen konnte, weil sein Protokoll dann aus einer früheren Kompilierung stammt.

### Bearbeiten

| Werkzeug | Was es tut |
|---|---|
| `write_file` | Eine Datei schreiben oder überschreiben |
| `replace_in_file` | Innerhalb einer Datei suchen und ersetzen |
| `create_file` | Eine Datei oder einen Ordner anlegen |
| `rename_file` | Einen Pfad umbenennen oder verschieben |
| `delete_file` | Eine Datei oder einen Ordner löschen |
| `set_main_doc` | Das Einstiegsdokument fürs Kompilieren festlegen |

### Kompilieren und Abbildungen

| Werkzeug | Was es tut |
|---|---|
| `compile` | Das Projekt zu PDF kompilieren |
| `preview_figure` | Eine Abbildung eigenständig rendern und als PNG-Bild zurückgeben |
| `insert_figure` | Die zuletzt vorgeschaute Abbildung in das Dokument einfügen |
| `load_image` | Ein Bild aus dem Projekt für Abbildungsarbeit laden |

`compile` sagt, ob der Build gelungen ist, listet seine Fehler auf, sagt, ob es ein PDF gibt, und endet mit dem letzten Teil des Protokolls. Ein Build, der fertig wurde, meldet auch seine Warnungen. Konnte der Build nicht laufen, wurde nicht fertig oder braucht etwas außerhalb des Quelltexts, etwa eine TeX-Installation oder eine Typst-Version, die fehlt, nennt das Ergebnis den Grund und die Abhilfe, die Oleafly Ihnen in der App anbietet. Das Werkzeug bittet den Client, es Ihnen zu sagen und Ihren Quelltext in Ruhe zu lassen. Eine Kompilierung, die Sie gestoppt haben, ist als gestoppt markiert, damit der Client sie nicht für einen Fehler im Code hält. Der eigene Assistent von Oleafly bekommt dasselbe Ergebnis.

Rufen Sie zuerst `get_status` auf, um zu erfahren, ob das Projekt LaTeX, Typst oder Markdown ist, und schreiben Sie dann Quelltext in diesem Format. `preview_figure` und `insert_figure` funktionieren in LaTeX- und Typst-Projekten:

- In LaTeX ist die Abbildung TikZ-Code, der in einem kleinen eigenständigen Dokument kompiliert wird, und `insert_figure` bettet sie in eine `figure`-Umgebung ein.
- In Typst ist die Abbildung Typst-Markup, etwa eine CeTZ-Leinwand oder ein fletcher-Diagramm, gerendert mit der Typst-Version des Projekts. `insert_figure` bettet sie in `#figure` ein, setzt das Label dahinter und zieht die zugehörigen `#import`-Zeilen über die Abbildung.
- In einem Markdown-Projekt geben beide Werkzeuge einen Fehler zurück und ändern nichts.

`load_image` funktioniert in jedem Projekt.

### App

| Werkzeug | Was es tut |
|---|---|
| `toggle_theme` | Hell-/Dunkelmodus umschalten |

### Skills

| Werkzeug | Was es tut |
|---|---|
| `list_skills` | Installierte Skills mit ID, Name, Beschreibung und ob sie eingeschaltet sind, auflisten |
| `load_skill` | Die vollständigen Anweisungen eines Skills und seine Dateiliste laden |
| `read_skill_file` | Eine Referenz oder ein Skript aus dem Ordner eines Skills lesen |

Die Skill-Werkzeuge funktionieren sofort nach dem Verbinden, ohne geöffnetes Projekt und ohne Oleafly-Fenster. Ein Client sieht jeden gültigen Skill, auch solche, die in den Einstellungen ausgeschaltet sind: Die Schalter entscheiden, welche Skills Oleaflys eigener Assistent verwendet, nicht was ein Client lesen darf. Agenten, die Skills stattdessen aus einem Ordner lesen, können **Skills mit anderen Agenten auf diesem Computer teilen** unter **Einstellungen → KI-Assistent → Skills** verwenden. Siehe [Skills](/docs/skills/).

### Notizen

Diese Werkzeuge sind da, solange **Notizen** unter **Einstellungen → Experimente** eingeschaltet ist, wie [Notizen einschalten](/docs/notes/#turn-on-notes) beschreibt. Sie arbeiten mit Ihren Notizen, nicht mit dem geöffneten Projekt, und brauchen ein verbundenes Fenster.

| Werkzeug | Was es tut |
|---|---|
| `list_knowledge_notes` | Ihre Notizen auflisten, die neueste zuerst, mit IDs, Titeln, Tags, verknüpften Projekten und kurzen Zusammenfassungen. Nach Tag oder Projekt filtern |
| `search_notes` | Ihre Notizen durchsuchen und IDs, Titel, Tags, Links und passende Ausschnitte zurückgeben |
| `read_note_by_id` | Eine Notiz als Markdown mit ihrem YAML-Kopf lesen |
| `today_note` | Die heutige Tagesnotiz lesen oder den Titel, den sie hätte, wenn es sie noch nicht gibt |
| `list_note_tasks` | Die Aufgaben mit Kontrollkästchen in Ihren Notizen auflisten, die neueste Notiz zuerst. Nach Notiz und nach offen oder erledigt filtern |
| `note_backlinks` | Die Notizen auflisten, die auf eine Notiz verlinken, mit dem Text um jeden Link |
| `append_to_note` | Markdown am Ende einer Notiz oder der heutigen Tagesnotiz hinzufügen |
| `edit_note_section` | Den Teil einer Notiz unter einer Überschrift umschreiben oder an dessen Ende etwas ergänzen |
| `create_note` | Eine Notiz mit Titel, Markdown, Tags und einem verknüpften Projekt anlegen |

`append_to_note` und `edit_note_section` schreiben nicht in die Notiz. Ihre Änderungen erscheinen darin als Vorschläge, bis Sie sie in Oleafly annehmen. `create_note` wartet auf Ihre Freigabe in Oleafly, ebenso `append_to_note`, wenn es zuerst die heutige Tagesnotiz anlegen muss. Unter **Dieser Verbindung vertrauen** fragt das Anlegen einer Notiz nicht nach. Eine Notiz, die über einen Kollaborationsserver geteilt ist, kann auf diese Weise gelesen, aber nicht geändert werden. **Nur lesen** entfernt die drei Werkzeuge, die Notizen ändern.

## Freigaben und Sicherheit

Viele MCP-Clients fragen nach, bevor sie ein Werkzeug aufrufen. Oleafly wendet zusätzlich die Richtlinie an, die unter **Einstellungen → Integrationen → Oleafly MCP** gewählt ist:

- **Jede Änderung bestätigen** ist die Voreinstellung. Schreibvorgänge, Umbenennungen und Löschungen zeigen eine Freigabekarte, solange ein App-Fenster verbunden ist. Ohne Fenster werden diese Vorgänge abgelehnt, weil es keinen Ort gibt, an dem die Karte erscheinen könnte.
- **Änderungen automatisch freigeben, Löschungen bestätigen** lässt Schreibvorgänge und Umbenennungen im Backend laufen. Löschungen brauchen weiterhin ein verbundenes Fenster zur Bestätigung.
- **Dieser Verbindung vertrauen** lässt Schreibvorgänge und Umbenennungen im Backend ohne Nachfrage durch Oleafly laufen. Löschen erfordert weiterhin ein verbundenes Fenster. Nutzen Sie diese Richtlinie nur, wenn Sie dem Client und seinen eigenen Freigabesteuerungen vertrauen.

Zwei weitere Schalter kommen hinzu:

- **Nur lesen** (eigener Schalter) entfernt die verändernden Werkzeuge vollständig aus `tools/list`, sodass eine externe App lesen und kompilieren, aber nie Dateien verändern kann, egal welche Richtlinie oben gilt.
- **Bearer-Token**: ein 256-Bit-Zufallswert, der authentifiziert verschlüsselt im lokalen Speicher unter `~/.oleafly/` liegt. Erzeugen Sie ihn neu, um alte Clients ungültig zu machen. Allgemeine Konfigurationsabrufe zeigen das Token nie. Nur die Verbindungssteuerungen des laufenden Servers können es in den Einstellungen sichtbar machen.

Und zwei unveränderliche Eigenschaften, die Sie nicht konfigurieren:

- **Nur Localhost**: Die Bind-Adresse ist `127.0.0.1`. Anfragen mit einem `Origin`-Header eines Browsers werden abgelehnt, und `Host` muss Loopback sein.
- **Projektbindung**: Die Dateiwerkzeuge des Backends akzeptieren projektrelative Pfade und beschränken kanonische Pfade auf das von der App gemeldete Projekt. Ein Werkzeugaufruf kann keine andere Projekt-ID angeben und das Backend nicht dazu bringen, ein anderes Bibliotheksprojekt zu wählen.

## Beim Arbeiten zusehen

Solange ein Fenster verbunden ist, protokolliert ein Reiter **MCP-Aktivität** die eingehenden Aufrufe. Backend-Aufrufe können nach dem Schließen des letzten Fensters weiterlaufen, aber es gibt keinen Aktivitätsbereich und keine Freigabekarte, bis sich ein Fenster erneut verbindet.

## Warum sich claude.ai im Browser nicht verbinden kann

Ein Cloud-Chatdienst kann `127.0.0.1` auf Ihrem Rechner nicht erreichen. Verwenden Sie stattdessen **Claude Desktop** (oder Claude Code, Cursor usw.). Tunneln Sie den MCP-Port nicht ins öffentliche Internet: Damit könnte jeder mit der URL Ihre lokalen Projektdateien bearbeiten und löschen.

## Fehlerbehebung

| Symptom | Was Sie versuchen können |
|---|---|
| Einige Werkzeuge sind nicht verfügbar | Abbildungsvorschauen und andere Werkzeuge, die nur die UI braucht, benötigen ein Oleafly-Fenster. Öffnen Sie App und Projekt und rufen Sie `tools/list` erneut auf. |
| Port weicht von `5323` ab | Der bevorzugte Port war nicht verfügbar, daher hat Oleafly einen freien gewählt. Kopieren Sie die aktive URL aus den Einstellungen. |
| HTTP 401 | Token stimmt nicht überein (zum Beispiel nach Neu erzeugen). Kopieren Sie das neue Token in den Client. |
| HTTP 403 | Der Client hat einen `Origin`-Header oder einen Nicht-Loopback-`Host` gesendet. Verwenden Sie einen nativen MCP-Client, keinen Browser-Reiter. |
| Aufruf mit Timeout | Jeder Werkzeugaufruf wartet bis zu **5 Minuten** (300 s) auf Kompilieren oder darauf, dass Sie auf Freigeben klicken. Genehmigen oder lehnen Sie offene Karten ab oder versuchen Sie es erneut. Eine Kompilierung kann länger dauern, bei einem Quarto- oder Calepin-Notebook bis zu einer Stunde. Sie läuft in Oleafly weiter, nachdem der Aufruf abgelaufen ist, und Werkzeuge, die das Oleafly-Fenster brauchen, warten darauf. Lassen Sie sie also fertig werden, bevor Sie es erneut versuchen. |
| `compile` liefert einen Grund statt Fehlern | Der Build konnte nicht laufen, zum Beispiel weil TeX nicht installiert ist. Nutzen Sie die Abhilfe, die Oleafly in der App anbietet, etwa TinyTeX zu installieren, und kompilieren Sie dann erneut. |
| Verbindung nicht möglich | Oleafly muss laufen und MCP aktiviert sein. Dieser Server stoppt, wenn Sie Oleafly beenden; für Projektwerkzeuge bei geschlossener App verbinden Sie den Client stattdessen mit `oleafly mcp`. |

## Externe Werkzeuge zu Oleafly hinzufügen

![Einstellungen → KI-Assistent → MCP. Einen Server hinzufügen, das Register durchstöbern oder Konfigurationen aus einem anderen Werkzeug importieren.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

Um dem eingebauten Assistenten mehr Werkzeuge zu geben, öffnen Sie **Einstellungen → KI-Assistent → MCP**.

- **Register durchstöbern**, um einen Server zu finden und seine Einrichtung zu prüfen.
- **Aus anderen Werkzeugen importieren**, um vorhandene Serverkonfigurationen auszuwählen. Prüfen Sie die gewählten Einträge vor dem Import.
- **Server hinzufügen**, um einen Server selbst einzutragen; prüfen Sie danach die Verbindung.

Verbundene Server stellen ihre Werkzeuge dem Assistenten zur Verfügung. Sie können den Verbindungsstatus einsehen und Server auf derselben Seite aktivieren oder deaktivieren. Zugangsdaten und Befehle gehören zu jeder einzelnen Serverkonfiguration; prüfen Sie sie, bevor Sie einen neuen Server verbinden.

alphaXiv verbindet sich ebenfalls als MCP-Server, doch Sie richten es stattdessen unter **Einstellungen → Integrationen → alphaXiv** mit einem API-Schlüssel ein. Sobald es verbunden ist, erscheint es in dieser Liste als **alphaXiv**. [Recherchequellen verbinden](/docs/integrations/research-sources/#alphaxiv) beschreibt die Schritte.

## Einen externen Server von Hand konfigurieren

![Server hinzufügen → Formular. Wählen Sie Lokaler Befehl oder Entfernte URL, füllen Sie die Verbindungsfelder aus und nutzen Sie dann Hinzufügen und Prüfen.](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

Wählen Sie unter **Einstellungen → KI-Assistent → MCP** den Eintrag **Server hinzufügen**. Ein lokaler Server führt einen Befehl über stdio aus; ein Remote-Server verbindet sich mit einer URL. Das JSON-Formular nutzt das Serverformat von Oleafly:

```json title="Konfiguration eines lokalen Servers"
{
  "name": "Research tools",
  "enabled": true,
  "transport": "stdio",
  "command": "your-mcp-server",
  "args": ["--stdio"],
  "env": {}
}
```

Ersetzen Sie Befehl und Argumente durch die vom installierten Server dokumentierten. Umgebungswerte gehören in das `env`-Objekt.

```json title="Konfiguration eines Remote-Servers"
{
  "name": "Research service",
  "enabled": true,
  "transport": "remote",
  "url": "https://your-server.example/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}
```

Ersetzen Sie Beispiel-URL und Beispiel-Token durch die Verbindungsdaten des Dienstes. Nutzen Sie **Prüfen**, um die Verbindung zu testen, und sehen Sie sich dann die Werkzeuge an, die der Server bereitstellt. Aktivieren oder deaktivieren Sie den Server in seiner Zeile. Nutzen Sie seine Bearbeiten-Aktion, um die Konfiguration zu ändern, und seine Entfernen-Aktion, um ihn zu trennen.

## Vorhandene MCP-Konfigurationen importieren

Wählen Sie **Aus anderen Werkzeugen importieren**, sehen Sie sich die gefundenen Konfigurationen an und wählen Sie die gewünschten Server. Prüfen Sie Pfade der Programme, Umgebungsvariablen, URLs und Zugangsdaten vor dem Import. Dies importiert Verbindungseinstellungen; es installiert nicht das Serverprogramm für Sie.

## Testen Sie die Verbindung

1. Öffnen Sie ein kleines Übungsprojekt in Oleafly.
2. Verbinden Sie den externen Client mit dem aus der App kopierten Snippet.
3. Bitten Sie den Client, `get_status` aufzurufen und die Projektdateien aufzulisten.
4. Bitten Sie ihn, das Hauptdokument zu lesen und eine Titeländerung vorzuschlagen.
5. Prüfen Sie die Aktion in Oleafly, bevor Sie einen Schreibvorgang freigeben.
6. Kompilieren Sie und sehen Sie sich das PDF an.

Beginnen Sie bei einem verbundenen externen Werkzeug in Oleafly mit einer einfachen Leseanfrage, die dieser Server unterstützt, und sehen Sie sich die entstehende Werkzeugkarte im Chat an.
