Verbindungen
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 einzufügen.
Aktivieren
Abschnitt betitelt „Aktivieren“- Öffnen Sie Einstellungen → Integrationen → Oleafly MCP.
- 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
Abschnitt betitelt „Verbinden Sie Ihren Client“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
Abschnitt betitelt „Claude Code“claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"Claude Desktop
Abschnitt betitelt „Claude Desktop“Fügen Sie dies zu claude_desktop_config.json hinzu (stdio-Brücke über mcp-remote, weil Desktop stdio bevorzugt):
{ "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
Abschnitt betitelt „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 (öffnet in einem neuen Tab) 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
Abschnitt betitelt „Cursor / VS Code“In .cursor/mcp.json (oder der MCP-Konfiguration Ihres Clients):
{ "mcpServers": { "oleafly": { "url": "http://127.0.0.1:5323/mcp", "headers": { "Authorization": "Bearer <token>" } } }}Grok CLI
Abschnitt betitelt „Grok CLI“In ~/.grok/config.toml:
[mcp_servers.oleafly]url = "http://127.0.0.1:5323/mcp"headers = { Authorization = "Bearer <token>" }Codex CLI
Abschnitt betitelt „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:
[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
Abschnitt betitelt „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
Abschnitt betitelt „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 |
| 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
Abschnitt betitelt „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
Abschnitt betitelt „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_figurebettet sie in einefigure-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_figurebettet sie in#figureein, 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.
| Werkzeug | Was es tut |
|---|---|
toggle_theme | Hell-/Dunkelmodus umschalten |
| 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.
Notizen
Abschnitt betitelt „Notizen“Diese Werkzeuge sind da, solange Notizen unter Einstellungen → Experimente eingeschaltet ist, wie Notizen einschalten 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
Abschnitt betitelt „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 einemOrigin-Header eines Browsers werden abgelehnt, undHostmuss 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
Abschnitt betitelt „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
Abschnitt betitelt „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
Abschnitt betitelt „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
Abschnitt betitelt „Externe Werkzeuge zu Oleafly hinzufügen“
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 beschreibt die Schritte.
Einen externen Server von Hand konfigurieren
Abschnitt betitelt „Einen externen Server von Hand konfigurieren“
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:
{ "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.
{ "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
Abschnitt betitelt „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
Abschnitt betitelt „Testen Sie die Verbindung“- Öffnen Sie ein kleines Übungsprojekt in Oleafly.
- Verbinden Sie den externen Client mit dem aus der App kopierten Snippet.
- Bitten Sie den Client,
get_statusaufzurufen und die Projektdateien aufzulisten. - Bitten Sie ihn, das Hauptdokument zu lesen und eine Titeländerung vorzuschlagen.
- Prüfen Sie die Aktion in Oleafly, bevor Sie einen Schreibvorgang freigeben.
- 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.