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

Related MCP server: Joplin MCP Server

Anforderungen

1. Joplin Desktop - Stellen Sie sicher, dass es installiert ist und läuft

2. Node.js 18+ - Erforderlich, um den MCP-Server auszuführen

3. Web Clipper aktiviert - Aktivieren Sie den Web Clipper-Dienst in Joplin

Installation & Einrichtung

1. Joplin Web Clipper aktivieren

1. Öffnen Sie die Joplin Desktop-Anwendung

2. Gehen Sie zu Extras → Optionen → Web Clipper

3. Aktivieren Sie Web Clipper-Dienst aktivieren

4. Notieren Sie sich die angezeigte Portnummer (normalerweise 41184)

5. 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

1. Bestätigen Sie, dass Joplin läuft

   • Die Joplin Desktop-Anwendung muss geöffnet bleiben

2. Überprüfen Sie die Web Clipper-Einstellungen

   • Stellen Sie sicher, dass der Web Clipper-Dienst aktiviert ist

   • Überprüfen Sie die Porteinstellungen (Standard 41184)

3. 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

1. Gehen Sie in Joplin zu Extras → Optionen → Web Clipper

2. Kopieren Sie das angezeigte Token

3. 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:

1. Überprüfen Sie, ob der Joplin Web Clipper normal läuft

2. Überprüfen Sie Fehlermeldungen und Protokolle

3. Reichen Sie ein Issue mit detaillierten Fehlerinformationen ein