Notion MCP

npx add-mcp 'https://mcp.notion.com/mcp'

Notion MCP Server

[!HINWEIS]

Für die beste Erfahrung verwenden Sie Remote Notion MCP, unseren offiziell gehosteten MCP-Server. Dieses Repository ist eine separate, selbst gehostete MCP-Server-Implementierung, die nicht mehr aktiv gewartet oder unterstützt wird. Bitte verwenden Sie stattdessen Remote Notion MCP. Es ist speziell dafür entwickelt, KI-Agenten schnellere Ergebnisse mit deutlich weniger Tokens zu liefern.

Remote Notion MCP kann Ihren Workspace und verbundene Apps semantisch durchsuchen, Seiten in Markdown lesen und bearbeiten und nur den relevantesten Kontext zurückgeben. Das bedeutet weniger Wartezeit, weniger Context-Window-Nutzung und geringere Token-Kosten. Es verwendet außerdem OAuth und respektiert automatisch die vorhandenen Notion-Berechtigungen jedes Benutzers – ohne API-Tokens, JSON-Konfiguration, manuelles Teilen von Seiten oder einen lokalen Server, der gewartet werden muss.

Funktion	Remote Notion MCP	Dieses Projekt (lokal)
Schnelle, gehostete Erfahrung	✅	Läuft und aktualisiert lokal
Token-effiziente Antworten	✅	Eingeschränkt
Leistungsstarke, auf KI-Agenten zugeschnittene Tools	✅	Grundlegende, von der API abgeleitete Tools
Semantische Suche in Ihrem Notion-Workspace	✅	Nur Stichwortsuche
KI-Connector-Suche über verbundene Apps	✅	Nicht verfügbar
Markdown-natives Lesen und Bearbeiten von Seiten	✅	Beschränkt auf zwei Seiteninhalt-Tools
Nahtlose OAuth-Einrichtung	✅	Manuelle Token- und JSON-Konfiguration
Respektiert vorhandene Notion-Berechtigungen jedes Benutzers	✅	Manuelle Integrationsberechtigungen und Seitenfreigabe
Aktive Unterstützung und fortlaufende Verbesserungen	✅	Nicht aktiv unterstützt

Erfahren Sie mehr und legen Sie los in der Remote Notion MCP-Dokumentation.

Wir priorisieren Remote Notion MCP und bieten nur dafür aktive Unterstützung. Daher:

• Wir werden dieses lokale MCP-Server-Repository in der Zukunft möglicherweise einstellen.
• Issues und Pull Requests hier werden nicht aktiv überwacht.
• Bitte reichen Sie keine Issues zum Remote-MCP hier ein; kontaktieren Sie stattdessen den Notion-Support.

Dieses Projekt implementiert einen MCP-Server für die Notion-API.

---

⚠️ Breaking Changes in Version 2.0.0

Version 2.0.0 migriert zur Notion-API 2025-09-03, die Datenquellen als primäre Abstraktion für Datenbanken einführt.

Was hat sich geändert

Entfernte Tools (3):

• post-database-query – ersetzt durch query-data-source
• update-a-database – ersetzt durch update-a-data-source
• create-a-database – ersetzt durch create-a-data-source

Neue Tools (7):

• query-data-source – Eine Datenquelle (Datenbank) mit Filtern und Sortierungen abfragen
• retrieve-a-data-source – Metadaten und Schema für eine Datenquelle abrufen
• update-a-data-source – Datenquellen-Eigenschaften aktualisieren
• create-a-data-source – Eine neue Datenquelle erstellen
• list-data-source-templates – Verfügbare Vorlagen in einer Datenquelle auflisten
• move-page – Eine Seite an einen anderen übergeordneten Speicherort verschieben
• retrieve-a-database – Datenbank-Metadaten einschließlich ihrer Datenquellen-IDs abrufen

Parameteränderungen:

• Alle Datenbankoperationen verwenden jetzt data_source_id anstelle von database_id
• Suchfilterwerte wurden von ["page", "database"] auf ["page", "data_source"] geändert
• Die Seitenerstellung unterstützt jetzt sowohl page_id- als auch database_id-Eltern (für Datenquellen)

Muss ich migrieren?

Keine Codeänderungen erforderlich. MCP-Tools werden beim Serverstart automatisch erkannt. Wenn Sie auf v2.0.0 aktualisieren, sehen KI-Clients automatisch die neuen Toolnamen und Parameter. Die alten Datenbank-Tools sind nicht mehr verfügbar.

Wenn Sie hartcodierte Toolnamen oder Prompts haben, die auf die alten Datenbank-Tools verweisen, aktualisieren Sie diese, um die neuen Datenquellen-Tools zu verwenden:

Altes Tool (v1.x)	Neues Tool (v2.0)	Parameteränderung
post-database-query	query-data-source	database_id → data_source_id
update-a-database	update-a-data-source	database_id → data_source_id
create-a-database	create-a-data-source	Keine Änderung (verwendet parent.page_id)

Hinweis: retrieve-a-database ist weiterhin verfügbar und gibt Datenbank-Metadaten einschließlich der Liste der Datenquellen-IDs zurück. Verwenden Sie retrieve-a-data-source, um das Schema und die Eigenschaften einer bestimmten Datenquelle abzurufen.

Gesamtzahl der Tools jetzt: 22 (waren 19 in v1.x)

---

Seiteninhalt als Markdown

Der Server stellt zwei Tools für die Arbeit mit Seiteninhalten als erweitertes Markdown anstelle von Block-JSON bereit, was für KI-Agenten deutlich token-effizienter ist:

• retrieve-page-markdown – Den vollständigen Inhalt einer Seite als Markdown lesen (GET /v1/pages/{page_id}/markdown). Übergeben Sie include_transcript: true, um Besprechungsnotiz-Transkripte inline einzufügen.
• update-page-markdown – Den Inhalt einer Seite mit Markdown bearbeiten (PATCH /v1/pages/{page_id}/markdown). Bevorzugen Sie replace_content, um die gesamte Seite zu überschreiben, oder update_content für gezielte Suchen-und-Ersetzen-Bearbeitungen.

Diese Endpunkte erfordern die Notion-API-Version 2026-03-11. Der Server bezieht den Notion-Version-Header jetzt pro Operation aus der OpenAPI-Spezifikation, sodass diese Tools 2026-03-11 verwenden, während der Rest der API weiterhin 2025-09-03 verwendet – keine Konfiguration erforderlich. Wenn Sie Notion-Version selbst über OPENAPI_MCP_HEADERS festlegen, hat Ihr Wert für jedes Tool Vorrang.

---

Installation

1. Einrichtung der Integration in Notion

Gehen Sie zu https://www.notion.so/profile/integrations und erstellen Sie eine neue interne Integration oder wählen Sie eine vorhandene aus.

Obwohl wir den Umfang der exponierten Notion-API begrenzen (z. B. können Sie Datenbanken nicht über MCP löschen), besteht ein Risiko ungleich Null für Workspace-Daten, wenn diese LLMs ausgesetzt werden. Sicherheitsbewusste Benutzer möchten möglicherweise die Capabilities der Integration weiter konfigurieren.

Sie können beispielsweise ein schreibgeschütztes Integrationstoken erstellen, indem Sie auf der Registerkarte „Configuration" nur „Read content"-Zugriff gewähren:

2. Verbinden von Inhalten mit der Integration

Stellen Sie sicher, dass relevante Seiten und Datenbanken mit Ihrer Integration verbunden sind.

Besuchen Sie dazu die Registerkarte Access in den Einstellungen Ihrer internen Integration. Bearbeiten Sie den Zugriff und wählen Sie die Seiten aus, die Sie verwenden möchten.

Alternativ können Sie den Seitenzugriff einzeln gewähren. Sie müssen die Zielseite besuchen, auf die 3 Punkte klicken und „Connect to integration" auswählen.

3. Hinzufügen der MCP-Konfiguration zu Ihrem Client

Mit npm

Cursor & Claude

Fügen Sie Folgendes zu Ihrer .cursor/mcp.json oder claude_desktop_config.json hinzu (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)

Option 1: Verwendung von NOTION_TOKEN (empfohlen)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Option 2: Verwendung von OPENAPI_MCP_HEADERS (für fortgeschrittene Anwendungsfälle)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
      }
    }
  }
}

Zed

Fügen Sie Folgendes zu Ihrer settings.json hinzu

{
  "context_servers": {
    "some-context-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
        }
      },
      "settings": {}
    }
  }
}

GitHub Copilot CLI

Verwenden Sie die Copilot-CLI, um den MCP-Server interaktiv hinzuzufügen:

/mcp add

Alternativ erstellen oder bearbeiten Sie die Konfigurationsdatei ~/.copilot/mcp-config.json und fügen Sie Folgendes hinzu:

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Weitere Informationen finden Sie in der Copilot-CLI-Dokumentation.

Mit Docker

Es gibt zwei Optionen zum Ausführen des MCP-Servers mit Docker:

Option 1: Verwendung des offiziellen Docker-Hub-Images

Fügen Sie Folgendes zu Ihrer .cursor/mcp.json oder claude_desktop_config.json hinzu

Verwendung von NOTION_TOKEN (empfohlen):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Verwendung von OPENAPI_MCP_HEADERS (für fortgeschrittene Anwendungsfälle):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "mcp/notion"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}"
      }
    }
  }
}

Dieser Ansatz:

• Verwendet das offizielle Docker-Hub-Image
• Behandelt JSON-Escaping über Umgebungsvariablen korrekt
• Bietet eine zuverlässigere Konfigurationsmethode

Option 2: Lokales Erstellen des Docker-Images

Sie können das Docker-Image auch lokal erstellen und ausführen. Erstellen Sie zuerst das Docker-Image:

docker compose build

Fügen Sie dann Folgendes zu Ihrer .cursor/mcp.json oder claude_desktop_config.json hinzu

Verwendung von NOTION_TOKEN (empfohlen):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}

Verwendung von OPENAPI_MCP_HEADERS (für fortgeschrittene Anwendungsfälle):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}",
        "notion-mcp-server"
      ]
    }
  }
}

Vergessen Sie nicht, ntn_**** durch Ihr Integrationsgeheimnis zu ersetzen. Sie finden es auf der Konfigurationsregisterkarte Ihrer Integration:

Transportoptionen

Der Notion MCP-Server unterstützt zwei Transportmodi:

STDIO-Transport (Standard)

Der Standard-Transportmodus verwendet Standardeingabe/-ausgabe für die Kommunikation. Dies ist der Standard-MCP-Transport, der von den meisten Clients wie Claude Desktop verwendet wird.

# Run with default stdio transport
npx @notionhq/notion-mcp-server

# Or explicitly specify stdio
npx @notionhq/notion-mcp-server --transport stdio

Streamable-HTTP-Transport

Für webbasierte Anwendungen oder Clients, die HTTP-Kommunikation bevorzugen, können Sie den Streamable-HTTP-Transport verwenden:

# Run with Streamable HTTP transport on port 3000 (default)
npx @notionhq/notion-mcp-server --transport http

# Run on a custom port
npx @notionhq/notion-mcp-server --transport http --port 8080

# Bind to a different host. The default is 127.0.0.1.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0

# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

Bei Verwendung des Streamable-HTTP-Transports ist der Server standardmäßig unter http://127.0.0.1:<port>/mcp verfügbar.

Authentifizierung

Der Streamable-HTTP-Transport erfordert aus Sicherheitsgründen eine Bearer-Token-Authentifizierung. Sie haben drei Optionen:

Option 1: Automatisch generiertes Token (nur für die Entwicklung)

npx @notionhq/notion-mcp-server --transport http

Der Server generiert ein sicheres Zufallstoken und schreibt es in eine Datei mit eingeschränkten Berechtigungen:

Generated auth token written to: /tmp/.notion-mcp-auth-token-12345

Option 2: Benutzerdefiniertes Token über die Befehlszeile (für die Produktion empfohlen)

npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

Option 3: Benutzerdefiniertes Token über Umgebungsvariable (für die Produktion empfohlen)

AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

Das Befehlszeilenargument --auth-token hat Vorrang vor der Umgebungsvariable AUTH_TOKEN, wenn beide angegeben sind.

Unsichere Option: HTTP-Authentifizierung deaktivieren

Sie können die Bearer-Token-Authentifizierung nur mit dem expliziten unsicheren Flag deaktivieren:

npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth

WARNUNG: --unsafe-disable-auth ist unsicher. Der Server kann für Seiten erreichbar sein, die Sie über DNS-Rebinding besuchen. Verwenden Sie ihn nur in einem isolierten Netzwerk.

Wenn die Authentifizierung deaktiviert ist, aktiviert der Server DNS-Rebinding-Schutz, indem er die Header Host und Origin gegen den konfigurierten lokalen Host und Loopback-Hosts prüft. Das vorherige Flag --disable-auth wird weiterhin als veraltetes Alias akzeptiert, gibt jedoch eine Warnung aus.

HTTP-Anfragen stellen

Alle Anfragen an den Streamable-HTTP-Transport müssen das Bearer-Token im Authorization-Header enthalten:

# Example request
curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Hinweis: Stellen Sie sicher, dass Sie entweder die Umgebungsvariable NOTION_TOKEN (empfohlen) oder die Umgebungsvariable OPENAPI_MCP_HEADERS mit Ihrem Notion-Integrationstoken festlegen, wenn Sie einen der beiden Transportmodi verwenden.

Bedienen mehrerer Integrationen (Per-Request-Token-Passthrough)

Standardmäßig authentifiziert sich der Server beim Start mit einem einzigen Token bei Notion, wodurch eine Bereitstellung an eine Notion-Integration gebunden ist. Um einer einzelnen Bereitstellung das Bedienen mehrerer Integrationen zu ermöglichen, aktivieren Sie den Token-Passthrough, sodass jeder Client sein eigenes Notion-Integrationstoken pro Verbindung bereitstellt:

# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough

Clients senden ihr Notion-Token dann in der initialize-Anfrage über den dedizierten Notion-Token-Header:

curl -H "Authorization: Bearer <server-auth-token>" \
     -H "Notion-Token: ntn_****" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

So wird das Token für jede Verbindung in dieser Reihenfolge aufgelöst:

1. Der Notion-Token-Header (bevorzugt – eindeutig und funktioniert neben der eigenen Authorization-Gateway-Authentifizierung des Servers). Wenn vorhanden, muss es ein gültiges Notion-Token sein, andernfalls wird die Anfrage mit 401 abgelehnt.
2. Authorization: Bearer ntn_**** – nur wenn die eigene Bearer-Authentifizierung des Servers deaktiviert ist (--unsafe-disable-auth), sodass der Header frei ist, das Notion-Token direkt zu tragen.
3. Andernfalls das Startumgebungs-Token (NOTION_TOKEN / OPENAPI_MCP_HEADERS), falls festgelegt, sodass Passthrough und eine Standardintegration auf einer Bereitstellung koexistieren können.

Hinweise:

• Nur Werte mit einem Notion-Token-Präfix (ntn_, Legacy secret_) werden als Notion-Tokens behandelt, sodass das Gateway-Geheimnis des Servers und das Notion-Token eines Mandanten niemals kollidieren.
• Jedes Token ist an seine MCP-Sitzung gebunden; Tokens werden niemals protokolliert (nur ein redigiertes Präfix wird ausgegeben).
• Dies ist ein bewusstes Token-Passthrough-Setup. Stellen Sie es immer über TLS bereit und bevorzugen Sie es, die eigene Bearer-Authentifizierung des Servers (--auth-token) als Gateway vor dem Multi-Tenant-Verkehr aktiviert zu lassen.

Beispiele

1. Verwenden Sie die folgende Anweisung

Comment "Hello MCP" on page "Getting started"

Die KI plant korrekt zwei API-Aufrufe, v1/search und v1/comments, um die Aufgabe zu erfüllen

1. Ebenso führt die folgende Anweisung zu einer neuen Seite mit dem Namen „Notion MCP", die zur übergeordneten Seite „Development" hinzugefügt wird

Add a page titled "Notion MCP" to page "Development"

1. Sie können auch direkt auf die Inhalts-ID verweisen

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Entwicklung

Build & Test

npm run build
npm test

Ausführen

npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

Testen von Änderungen lokal in Cursor:

1. Führen Sie den Befehl npm link vom Repository-Stammverzeichnis aus, um einen maschinenweiten Symlink zum Paket notion-mcp-server zu erstellen.
2. Fügen Sie den untenstehenden Konfigurationsausschnitt in die Datei mcp.json von Cursor ein (oder in einen anderen MCP-Client, mit dem Sie testen möchten).
3. (Bereinigung) Führen Sie npm unlink vom Repository-Stammverzeichnis aus.

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

Veröffentlichen

npm login
npm publish --access public