MCP Joplin Server

Ein Model Context Protocol (MCP) Server, der sich in Joplin-Notizen integriert und es KI-Clients (wie Perplexity) ermöglicht, über die Web Clipper API von Joplin auf Ihre Notizbücher und Notizen zuzugreifen und diese zu bearbeiten.

Funktionen

🔍 Suchfunktion: Durchsuchen von Notizen und Notizbüchern
📖 Inhalt lesen: Abrufen des vollständigen Inhalts spezifischer Notizen
📝 Erstellungsfunktionen: Erstellen neuer Notizen und Notizbücher
✏️ Aktualisierungs-/Bearbeitungsfunktionen: Aktualisieren von Notizinhalten, Anhängen an Notizen und Umbenennen von Notizbüchern
🗑️ Löschfunktionen: Löschen von Notizen und Notizbüchern (unterstützt Papierkorb oder endgültiges Löschen)
🔄 Verschiebefunktion: Verschieben von Notizen in andere Notizbücher
📋 Listenfunktion: Auflisten aller Notizbücher und Notizen innerhalb spezifischer Notizbücher

Anforderungen

Joplin Desktop - Stellen Sie sicher, dass es installiert ist und läuft
Node.js 18+ - Erforderlich, um den MCP-Server auszuführen
Web Clipper aktiviert - Aktivieren Sie den Web Clipper-Dienst in Joplin

Installation & Einrichtung

1. Joplin Web Clipper aktivieren

Öffnen Sie die Joplin Desktop-Anwendung
Gehen Sie zu Extras → Optionen → Web Clipper
Aktivieren Sie Web Clipper-Dienst aktivieren
Notieren Sie sich die angezeigte Portnummer (normalerweise 41184)
Kopieren Sie das API-Token (falls eine Authentifizierung erforderlich ist)

2. MCP Joplin Server installieren

# Clone or download this project
cd mcp-joplin

# Install dependencies
npm install

# Compile TypeScript
npm run build

3. Testausführung

# Run directly (will auto-detect Joplin service)
npm start

# Or specify port
npm start -- --port 41184

# Or specify token (if needed)
npm start -- --token YOUR_API_TOKEN

# View help
npm start -- --help

4. Verwendung von npx

# Global installation (recommended)
npm install -g .

# Then use anywhere
npx mcp-joplin

# Or run locally
npx . --port 41184

MCP-Client-Konfiguration

Konfiguration von Perplexity oder anderen MCP-Clients

Fügen Sie die folgende Konfiguration zu Ihrer MCP-Client-Konfigurationsdatei hinzu:

🔐 Konfiguration (API-Token erforderlich)

Dieser MCP-Server benötigt ein Joplin-API-Token, um ordnungsgemäß zu funktionieren:

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-joplin",
        "--port",
        "41184",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

💡 Wichtig: Das API-Token ist erforderlich, damit dieser MCP-Server ordnungsgemäß funktioniert.

Beispiel für die Claude Desktop-Konfiguration

Claude Desktop-Konfiguration

In ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/Users/yourusername/path/to/mcp-joplin",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

Verfügbare MCP-Tools

1. get_note_content

Abrufen des vollständigen Inhalts einer bestimmten Notiz

Parameters: noteId (string) - The ID of the note

2. search_notes

Nach Notizen suchen

Parameters:
- query (string) - Search keywords
- limit (number, optional) - Result limit (default: 20)

3. search_notebooks

Nach Notizbüchern suchen

Parameters: query (string) - Search keywords

4. list_notebooks

Alle Notizbücher auflisten

Parameters: None

5. list_notes

Notizen in einem bestimmten Notizbuch auflisten

Parameters:
- notebookId (string) - The ID of the notebook
- limit (number, optional) - Result limit (default: 50)

5.1. list_sub_notebooks

Untergeordnete Notizbücher innerhalb eines bestimmten Notizbuchs auflisten

Parameters:
- parentNotebookId (string) - The ID of the parent notebook

6. create_note

Eine neue Notiz erstellen

Parameters:
- title (string) - Note title
- body (string) - Note content (Markdown format)
- notebookId (string, optional) - Target notebook ID

7. create_notebook

Ein neues Notizbuch erstellen

Parameters:
- title (string) - Notebook title
- parentId (string, optional) - Parent notebook ID (for sub-notebooks)

8. delete_note

Eine Notiz löschen

Parameters:
- noteId (string) - ID of the note to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

9. delete_notebook

Ein Notizbuch löschen

Parameters:
- notebookId (string) - ID of the notebook to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

10. move_note

Eine Notiz in ein anderes Notizbuch verschieben

Parameters:
- noteId (string) - ID of the note to move
- targetNotebookId (string) - Target notebook ID

11. update_note

Den Titel und/oder den Text einer bestehenden Notiz aktualisieren

Parameters:
- noteId (string) - ID of the note to update
- title (string, optional) - New note title
- body (string, optional) - New note content (full replacement, not a patch)

Hinweise:

Mindestens title oder body muss angegeben werden
Verwenden Sie dies, wenn Sie den Notizinhalt ersetzen oder eine Notiz umbenennen möchten

12. append_to_note

Inhalt an das Ende einer bestehenden Notiz anhängen

Parameters:
- noteId (string) - ID of the note to append to
- content (string) - Content to append
- separator (string, optional) - Separator inserted before appended content (default: "\n\n")

Hinweise:

Verwenden Sie dies für Protokolle, Besprechungsnotizen, ergänzende Informationen oder Testergebnisse
Bevorzugen Sie dies gegenüber update_note, wenn das Ziel darin besteht, Inhalte hinzuzufügen, ohne den bestehenden Text zu ersetzen

13. update_notebook

Den Titel eines bestehenden Notizbuchs aktualisieren

Parameters:
- notebookId (string) - ID of the notebook to update
- title (string) - New notebook title

14. scan_unchecked_items

Notizbücher und untergeordnete Notizbücher nach unerledigten Aufgaben (- [ ]) durchsuchen

Parameters:
- notebookId (string) - ID of the notebook to scan
- includeSubNotebooks (boolean, optional) - Whether to recursively scan sub-notebooks (default: true)

Bearbeitungssemantik

Verwenden Sie update_note, um den Titel und/oder den Text einer Notiz zu ersetzen
Verwenden Sie append_to_note, um Inhalte an das Ende einer Notiz anzuhängen, während der bestehende Inhalt erhalten bleibt
Verwenden Sie move_note, um das Notizbuch zu ändern, zu dem eine Notiz gehört
Verwenden Sie update_notebook, um ein Notizbuch umzubenennen

Anwendungsbeispiele

Konversationsbeispiele in KI-Clients:

You: "Search for notes containing 'Python'"
AI: Using search_notes tool to search for relevant notes...

You: "Create a new notebook called 'Learning Plan'"
AI: Using create_notebook tool to create a new notebook...

You: "Create a note about JavaScript in the Learning Plan notebook"
AI: Using list_notebooks to find the notebook ID, then using create_note to create the note...

You: "Show the complete content of a specific note"
AI: Using get_note_content tool to retrieve note content...

You: "Update the title of note abc123 to Weekly Review"
AI: Using update_note tool to rename the note...

You: "Append these test results to note abc123"
AI: Using append_to_note tool to add the new content to the end of the note...

You: "Rename notebook xyz789 to Project Archive"
AI: Using update_notebook tool to rename the notebook...

You: "Scan my project notebook for all uncompleted todo items"
AI: Using scan_unchecked_items tool to scan all sub-notebooks...

Fehlerbehebung

Verbindungsprobleme

Bestätigen Sie, dass Joplin läuft
- Die Joplin Desktop-Anwendung muss geöffnet bleiben
Überprüfen Sie die Web Clipper-Einstellungen
- Stellen Sie sicher, dass der Web Clipper-Dienst aktiviert ist
- Überprüfen Sie die Porteinstellungen (Standard 41184)

Fehlermeldungen anzeigen

# Use verbose mode to see errors
DEBUG=* npm start

Häufige Fehler

"Joplin Web Clipper service not found": Stellen Sie sicher, dass Joplin läuft und der Web Clipper aktiviert ist
"Connection refused": Überprüfen Sie, ob die Porteinstellungen korrekt sind
"Unauthorized" oder "403 Forbidden": API-Token ist erforderlich (siehe Anweisungen unten)

🔑 API-Token erforderlich

Ein API-Token ist erforderlich, damit dieser MCP-Server ordnungsgemäß funktioniert.

Abrufen eines API-Tokens

Gehen Sie in Joplin zu Extras → Optionen → Web Clipper
Kopieren Sie das angezeigte Token
Fügen Sie --token IHR_TOKEN zum Startbefehl hinzu

Entwicklung

# Run in development mode
npm run dev

# Compile
npm run build

# Prepare for publishing
npm run prepublishOnly

Technische Architektur

Sprache: TypeScript/Node.js
MCP SDK: @modelcontextprotocol/sdk
HTTP-Client: axios
CLI: commander
API: Joplin Web Clipper API

Technische Details

Notizbuchsuche: Aufgrund von Einschränkungen in der Such-API von Joplin für Ordnersuchen verwenden wir clientseitige Filterung, um die Notizbuch-Suchfunktion zu implementieren
Paginierungsbehandlung: Behandelt automatisch den Paginierungsmechanismus der Joplin-API (Standard 100 Elemente pro Seite), wodurch sichergestellt wird, dass vollständige Notizbuch- und Notizlisten abgerufen werden, was das Problem der unvollständigen Anzeige von untergeordneten Notizbüchern löst
Fehlerbehandlung: Vollständiger Fehlerbehandlungsmechanismus, einschließlich Joplin-API-Fehlern und Netzwerkverbindungsfehlern
Automatische Erkennung: Unterstützt die automatische Erkennung des Joplin Web Clipper-Ports (41184-41194)

Lizenz

MIT-Lizenz

Mitwirken

Probleme und Pull Requests sind willkommen!

Support

Wenn Sie auf Probleme stoßen, bitte:

Überprüfen Sie, ob der Joplin Web Clipper normal läuft
Überprüfen Sie Fehlermeldungen und Protokolle
Reichen Sie ein Issue mit detaillierten Fehlerinformationen ein