Notion MCP Server

Notion MCP Server

MCP-Server für die Notion-API, der LLM die Interaktion mit Notion-Arbeitsbereichen ermöglicht. Zusätzlich nutzt er Markdown-Konvertierung, um die Kontextgröße bei der Kommunikation mit LLMs zu reduzieren, die Token-Nutzung zu optimieren und Interaktionen effizienter zu gestalten.

Aufstellen

Hier finden Sie eine detaillierte Erklärung der oben genannten Schritte in den folgenden Artikeln:

• Englische Version: https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h
• Japanische Version: https://qiita.com/suekou/items/44c864583f5e3e6325d9

1. Erstellen Sie eine Notion-Integration :
   • Besuchen Sie die Notion-Seite „Ihre Integrationen“ .
   • Klicken Sie auf „Neue Integration“.
   • Benennen Sie Ihre Integration und wählen Sie entsprechende Berechtigungen aus (z. B. „Inhalt lesen“, „Inhalt aktualisieren“).
2. Rufen Sie den geheimen Schlüssel ab :
   • Kopieren Sie das „Interne Integrationstoken“ aus Ihrer Integration.
   • Dieses Token wird zur Authentifizierung verwendet.
3. Fügen Sie die Integration zu Ihrem Arbeitsbereich hinzu :
   • Öffnen Sie in Notion die Seite oder Datenbank, auf die die Integration zugreifen soll.
   • Klicken Sie oben rechts auf die Schaltfläche „···“.
   • Klicken Sie auf die Schaltfläche „Verbindungen“ und wählen Sie die Integration aus, die Sie oben in Schritt 1 erstellt haben.
4. Konfigurieren Sie Claude Desktop : Fügen Sie Folgendes zu Ihrer claude_desktop_config.json hinzu:

oder

Umgebungsvariablen

• NOTION_API_TOKEN (erforderlich): Ihr Notion API-Integrationstoken.
• NOTION_MARKDOWN_CONVERSION : Setzen Sie diese Option auf „true“, um die experimentelle Markdown-Konvertierung zu aktivieren. Dies kann den Token-Verbrauch beim Anzeigen von Inhalten erheblich reduzieren, kann jedoch beim Bearbeiten von Seiteninhalten zu Problemen führen.

Befehlszeilenargumente

• --enabledTools : Komma-getrennte Liste der zu aktivierenden Tools (z. B. „notion_retrieve_page,notion_query_database“). Wenn angegeben, sind nur die aufgelisteten Tools verfügbar. Wenn nicht angegeben, sind alle Tools aktiviert.

Beispiel für schreibgeschützte Tools (kopieren und einfügen möglich):

Erweiterte Konfiguration

Markdown-Konvertierung

Standardmäßig werden alle Antworten im JSON-Format zurückgegeben. Sie können die experimentelle Markdown-Konvertierung aktivieren, um den Token-Verbrauch zu reduzieren:

oder

Wenn NOTION_MARKDOWN_CONVERSION auf "true" gesetzt ist, werden Antworten in das Markdown-Format konvertiert (wenn format auf "markdown" gesetzt ist). Dadurch werden sie für Menschen besser lesbar und der Token-Verbrauch wird deutlich reduziert. Da diese Funktion jedoch experimentell ist, kann es beim Bearbeiten von Seiteninhalten zu Problemen kommen, da die ursprüngliche Struktur bei der Konvertierung verloren geht.

Sie können das Format für jede Anfrage einzeln steuern, indem Sie den format in Ihren Toolaufrufen entweder auf "json" oder "markdown" setzen:

• Verwenden Sie "markdown" für eine bessere Lesbarkeit, wenn Sie nur Inhalte anzeigen
• Verwenden Sie "json" wenn Sie den zurückgegebenen Inhalt ändern müssen

Fehlerbehebung

Wenn Berechtigungsfehler auftreten:

1. Stellen Sie sicher, dass die Integration über die erforderlichen Berechtigungen verfügt.
2. Überprüfen Sie, ob die Integration zu den entsprechenden Seiten oder Datenbanken eingeladen wird.
3. Bestätigen Sie, dass das Token und die Konfiguration in claude_desktop_config.json richtig eingestellt sind.

Projektstruktur

Das Projekt ist modular aufgebaut, um die Wartbarkeit und Lesbarkeit zu verbessern:

Verzeichnisbeschreibungen

• index.ts : Anwendungseinstiegspunkt. Analysiert Befehlszeilenargumente und startet den Server.
• client/ : Modul, das für die Kommunikation mit der Notion-API verantwortlich ist.
  • index.ts : Die Klasse NotionClientWrapper implementiert alle API-Aufrufe.
• server/ : MCP-Serverimplementierung.
  • index.ts : Verarbeitet von Claude empfangene Anfragen und ruft entsprechende Clientmethoden auf.
• types/ : Modul zur Typdefinition.
  • index.ts : Exporte für alle Typen.
  • args.ts : Schnittstellendefinitionen für Toolargumente.
  • common.ts : Definitionen für allgemeine Schemata (ID-Formate, Rich Text usw.).
  • responses.ts : Typdefinitionen für Notion-API-Antworten.
  • schemas.ts : Definitionen für MCP-Toolschemata.
• utils/ : Hilfsfunktionen.
  • index.ts : Funktionen wie das Filtern aktivierter Tools.
• markdown/ : Markdown-Konvertierungsfunktion.
  • index.ts : Logik zum Konvertieren von JSON-Antworten in das Markdown-Format.

Werkzeuge

Alle Tools unterstützen die folgenden optionalen Parameter:

• format (Zeichenfolge, „JSON“ oder „Markdown“, Standard: „Markdown“): Steuert das Antwortformat. Verwenden Sie „Markdown“ für lesbare Ausgabe, „JSON“ für den programmatischen Zugriff auf die ursprüngliche Datenstruktur. Hinweis: Die Markdown-Konvertierung funktioniert nur, wenn die Umgebungsvariable NOTION_MARKDOWN_CONVERSION auf „true“ gesetzt ist.

1. notion_append_block_children
   • Fügen Sie untergeordnete Blöcke an einen übergeordneten Block an.
   • Erforderliche Eingaben:
     • block_id (Zeichenfolge): Die ID des übergeordneten Blocks.
     • children (Array): Array von anzuhängenden Blockobjekten.
   • Gibt zurück: Informationen zu den angehängten Blöcken.
2. notion_retrieve_block
   • Rufen Sie Informationen zu einem bestimmten Block ab.
   • Erforderliche Eingaben:
     • block_id (Zeichenfolge): Die ID des abzurufenden Blocks.
   • Gibt zurück: Detaillierte Informationen zum Block.
3. notion_retrieve_block_children
   • Rufen Sie die untergeordneten Elemente eines bestimmten Blocks ab.
   • Erforderliche Eingaben:
     • block_id (Zeichenfolge): Die ID des übergeordneten Blocks.
   • Optionale Eingaben:
     • start_cursor (Zeichenfolge): Cursor für die nächste Ergebnisseite.
     • page_size (Zahl, Standard: 100, Max.: 100): Anzahl der abzurufenden Blöcke.
   • Gibt zurück: Liste der untergeordneten Blöcke.
4. notion_delete_block
   • Löschen Sie einen bestimmten Block.
   • Erforderliche Eingaben:
     • block_id (Zeichenfolge): Die ID des zu löschenden Blocks.
   • Rückgabe: Bestätigung der Löschung.
5. notion_retrieve_page
   • Rufen Sie Informationen zu einer bestimmten Seite ab.
   • Erforderliche Eingaben:
     • page_id (Zeichenfolge): Die ID der abzurufenden Seite.
   • Gibt zurück: Detaillierte Informationen zur Seite.
6. notion_update_page_properties
   • Aktualisieren Sie die Eigenschaften einer Seite.
   • Erforderliche Eingaben:
     • page_id (Zeichenfolge): Die ID der zu aktualisierenden Seite.
     • properties (Objekt): Zu aktualisierende Eigenschaften.
   • Gibt zurück: Informationen zur aktualisierten Seite.
7. notion_create_database
   • Erstellen Sie eine neue Datenbank.
   • Erforderliche Eingaben:
     • parent (object): Übergeordnetes Objekt der Datenbank.
     • properties (Objekt): Eigenschaftsschema der Datenbank.
   • Optionale Eingaben:
     • title (Array): Titel der Datenbank als Rich-Text-Array.
   • Gibt zurück: Informationen über die erstellte Datenbank.
8. notion_query_database
   • Führen Sie eine Datenbankabfrage durch.
   • Erforderliche Eingaben:
     • database_id (Zeichenfolge): Die ID der abzufragenden Datenbank.
   • Optionale Eingaben:
     • filter (Objekt): Filterbedingungen.
     • sorts (Array): Sortierbedingungen.
     • start_cursor (Zeichenfolge): Cursor für die nächste Ergebnisseite.
     • page_size (Zahl, Standard: 100, Maximum: 100): Anzahl der abzurufenden Ergebnisse.
   • Gibt zurück: Liste der Ergebnisse der Abfrage.
9. notion_retrieve_database
   • Rufen Sie Informationen zu einer bestimmten Datenbank ab.
   • Erforderliche Eingaben:
     • database_id (Zeichenfolge): Die ID der abzurufenden Datenbank.
   • Gibt zurück: Detaillierte Informationen zur Datenbank.
10. notion_update_database

• Aktualisieren Sie Informationen zu einer Datenbank.
• Erforderliche Eingaben:
  • database_id (Zeichenfolge): Die ID der zu aktualisierenden Datenbank.
• Optionale Eingaben:
  • title (Array): Neuer Titel für die Datenbank.
  • description (Array): Neue Beschreibung für die Datenbank.
  • properties (Objekt): Aktualisiertes Eigenschaftenschema.
• Gibt zurück: Informationen zur aktualisierten Datenbank.

11. notion_create_database_item

• Erstellen Sie ein neues Element in einer Notion-Datenbank.
• Erforderliche Eingaben:
  • database_id (Zeichenfolge): Die ID der Datenbank, zu der das Element hinzugefügt werden soll.
  • properties (Objekt): Die Eigenschaften des neuen Elements. Diese sollten dem Datenbankschema entsprechen.
• Gibt zurück: Informationen zum neu erstellten Artikel.

12. notion_search

• Durchsuchen Sie Seiten oder Datenbanken nach Titel.
• Optionale Eingaben:
  • query (Zeichenfolge): Text, nach dem in Seiten- oder Datenbanktiteln gesucht werden soll.
  • filter (Objekt): Kriterien zum Beschränken der Ergebnisse auf entweder nur Seiten oder nur Datenbanken.
  • sort (Objekt): Kriterien zum Sortieren der Ergebnisse
  • start_cursor (Zeichenfolge): Startcursor für die Seitennummerierung.
  • page_size (Zahl, Standard: 100, Maximum: 100): Anzahl der abzurufenden Ergebnisse.
• Gibt zurück: Liste der übereinstimmenden Seiten oder Datenbanken.

13. notion_list_all_users

• Listen Sie alle Benutzer im Notion-Arbeitsbereich auf.
• Hinweis: Diese Funktion erfordert ein Upgrade auf den Notion Enterprise-Plan und die Verwendung eines Organisations-API-Schlüssels, um Berechtigungsfehler zu vermeiden.
• Optionale Eingaben:
  • start_cursor (Zeichenfolge): Startcursor für die Seitennummerierung zum Auflisten von Benutzern.
  • Seitengröße (Zahl, max.: 100): Anzahl der abzurufenden Benutzer.
• Gibt zurück: Eine paginierte Liste aller Benutzer im Arbeitsbereich.

14. notion_retrieve_user

• Rufen Sie in Notion einen bestimmten Benutzer anhand der Benutzer-ID ab.
• Hinweis: Diese Funktion erfordert ein Upgrade auf den Notion Enterprise-Plan und die Verwendung eines Organisations-API-Schlüssels, um Berechtigungsfehler zu vermeiden.
• Erforderliche Eingaben:
  • user_id (Zeichenfolge): Die ID des abzurufenden Benutzers.
• Gibt zurück: Detaillierte Informationen zum angegebenen Benutzer.

15. notion_retrieve_bot_user

• Rufen Sie den Bot-Benutzer ab, der mit dem aktuellen Token in Notion verknüpft ist.
• Gibt zurück: Informationen zum Bot-Benutzer, einschließlich Details der Person, die die Integration autorisiert hat.

16. notion_create_comment

• Erstellen Sie einen Kommentar in Notion.
• Erfordert, dass die Integration über die Funktion „Kommentare einfügen“ verfügt.
• Geben Sie entweder ein parent Objekt mit einer page_id oder einer discussion_id an, aber nicht beides.
• Erforderliche Eingaben:
  • rich_text (Array): Array von Rich-Text-Objekten, die den Kommentarinhalt darstellen.
• Optionale Eingaben:
  • parent (Objekt): Muss page_id enthalten, falls verwendet.
  • discussion_id (Zeichenfolge): Eine vorhandene Diskussionsthread-ID.
• Gibt zurück: Informationen zum erstellten Kommentar.

17. notion_retrieve_comments

• Rufen Sie eine Liste ungelöster Kommentare von einer Notion-Seite oder einem Notion-Block ab.
• Erfordert, dass die Integration über die Funktion „Kommentare lesen“ verfügt.
• Erforderliche Eingaben:
  • block_id (Zeichenfolge): Die ID des Blocks oder der Seite, deren Kommentare Sie abrufen möchten.
• Optionale Eingaben:
  • start_cursor (Zeichenfolge): Startcursor für die Seitennummerierung.
  • page_size (Zahl, max.: 100): Anzahl der abzurufenden Kommentare.
• Gibt zurück: Eine paginierte Liste von Kommentaren, die mit dem angegebenen Block oder der angegebenen Seite verknüpft sind.

Lizenz

Dieser MCP-Server ist unter der MIT-Lizenz lizenziert. Das bedeutet, dass Sie die Software unter den Bedingungen der MIT-Lizenz frei verwenden, ändern und verbreiten dürfen. Weitere Informationen finden Sie in der LICENSE-Datei im Projekt-Repository.