Notion MCP

Notion MCP Server

[!NOTE]

Wir haben Notion MCP eingeführt, einen entfernten MCP-Server mit den folgenden Verbesserungen:

• Einfache Installation über Standard-OAuth. Kein Hantieren mit JSON oder API-Token mehr nötig.
• Leistungsstarke, auf KI-Agenten zugeschnittene Werkzeuge, einschließlich der Bearbeitung von Seiten in Markdown. Diese Werkzeuge sind auf optimierten Token-Verbrauch ausgelegt.

Weitere Informationen und den Einstieg finden Sie in der Notion MCP-Dokumentation.

Wir priorisieren und bieten aktiven Support nur für Notion MCP (remote). Daraus folgt:

• Möglicherweise stellen wir dieses lokale MCP-Server-Repository in Zukunft ein.
• Issues und Pull Requests werden hier nicht aktiv überwacht.
• Bitte melden Sie hier keine Issues, die den entfernten MCP betreffen; wenden Sie sich stattdessen an 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 auf die Notion API 2025-09-03, die Datenquellen als primäre Abstraktion für Datenbanken einführt.

Was hat sich geändert?

Entfernte Werkzeuge (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 Werkzeuge (7):

• query-data-source – Eine Datenquelle (Datenbank) mit Filtern und Sortierungen abfragen
• retrieve-a-data-source – Metadaten und Schema einer Datenquelle abrufen
• update-a-data-source – Eigenschaften einer Datenquelle 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 als übergeordnete Elemente (für Datenquellen)

Muss ich migrieren?

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

Falls Sie hartcodierte Werkzeugnamen oder Prompts haben, die auf die alten Datenbankwerkzeuge verweisen, aktualisieren Sie diese auf die neuen Datenquellen-Werkzeuge:

Altes Werkzeug (v1.x)	Neues Werkzeug (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 Werkzeuge jetzt: 22 (vorher 19 in v1.x)

---

Seiteninhalt als Markdown

Der Server stellt zwei Werkzeuge 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 gesamten Inhalt einer Seite als Markdown lesen (GET /v1/pages/{page_id}/markdown). Übergeben Sie include_transcript: true, um Transkripte von Besprechungsnotizen einzubetten.
• 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 Werkzeuge 2026-03-11 verwenden, während der Rest der API weiterhin 2025-09-03 nutzt – keine Konfiguration erforderlich. Wenn Sie Notion-Version selbst über OPENAPI_MCP_HEADERS setzen, hat Ihr Wert für jedes Werkzeug Vorrang.

---

Installation

1. Integration in Notion einrichten

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

Obwohl wir den Umfang der offengelegten Notion-API einschränken (Sie können beispielsweise keine Datenbanken über MCP löschen), besteht ein gewisses Risiko für die Arbeitsbereichsdaten, wenn diese LLMs zugänglich gemacht werden. Sicherheitsbewusste Benutzer möchten möglicherweise die Berechtigungen der Integration weiter konfigurieren.

Sie können beispielsweise ein schreibgeschütztes Integrationstoken erstellen, indem Sie im Tab „Konfiguration“ nur den Zugriff „Inhalte lesen“ gewähren:

2. Inhalte mit der Integration verbinden

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

Besuchen Sie dazu den Tab Zugriff 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. Rufen Sie dazu die Zielseite auf, klicken Sie auf die 3 Punkte und wählen Sie „Mit Integration verbinden“.

3. MCP-Konfiguration zu Ihrem Client hinzufügen

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: NOTION_TOKEN verwenden (empfohlen)

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

Option 2: OPENAPI_MCP_HEADERS verwenden (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 können Sie die Konfigurationsdatei ~/.copilot/mcp-config.json erstellen oder bearbeiten und Folgendes hinzufügen:

{
  "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 Möglichkeiten, den MCP-Server mit Docker auszuführen:

Option 1: Das offizielle Docker Hub-Image verwenden

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

Mit NOTION_TOKEN (empfohlen):

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

Mit 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 korrekt über Umgebungsvariablen
• Bietet eine zuverlässigere Konfigurationsmethode

Option 2: Das Docker-Image lokal bauen

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

docker compose build

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

Mit NOTION_TOKEN (empfohlen):

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

Mit 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 im Konfigurationstab Ihrer Integration:

Transportoptionen

Der Notion MCP Server unterstützt zwei Transportmodi:

STDIO-Transport (Standard)

Der Standard-Transportmodus verwendet die Standardeingabe/-ausgabe für die Kommunikation. Dies ist der standardmäßige 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 Möglichkeiten:

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 mit eingeschränkten Berechtigungen in eine Datei:

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

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

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

Option 3: Benutzerdefiniertes Token über eine Umgebungsvariable (für 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, falls beide angegeben werden.

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 könnte für von Ihnen besuchte Seiten über DNS-Rebinding erreichbar sein. Verwenden Sie dies nur in einem isolierten Netzwerk.

Wenn die Authentifizierung deaktiviert ist, aktiviert der Server den DNS-Rebinding-Schutz, indem er die Header Host und Origin mit dem konfigurierten lokalen Host und den Loopback-Hosts abgleicht. Das vorherige Flag --disable-auth wird weiterhin als veralteter 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 setzen, wenn Sie einen der Transportmodi verwenden.

Mehrere Integrationen bedienen (Token-Durchleitung pro Anfrage)

Standardmäßig authentifiziert sich der Server beim Start mit einem einzigen fest integrierten Token gegenüber Notion, was eine Bereitstellung an eine Notion-Integration bindet. Um einer einzelnen Bereitstellung die Bedienung mehrerer Integrationen zu ermöglichen, aktivieren Sie die Token-Durchleitung, 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 bei 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 aufgelöst, in dieser Reihenfolge:

1. Der Notion-Token-Header (bevorzugt – eindeutig und funktioniert neben der eigenen Authorization-Gateway-Authentifizierung des Servers). Falls 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 das Notion-Token direkt übertragen kann.
3. Andernfalls das Startup-Env-Token (NOTION_TOKEN / OPENAPI_MCP_HEADERS), falls gesetzt, sodass Durchleitung und eine Standardintegration in einer Bereitstellung koexistieren können.

Hinweise:

• Nur Werte mit einem Notion-Token-Präfix (ntn_, veraltet secret_) werden als Notion-Token behandelt, sodass das Gateway-Geheimnis des Servers und das Notion-Token eines Mandanten niemals kollidieren.
• Jedes Token ist an seine MCP-Sitzung gebunden; Token werden niemals protokolliert (es wird nur ein geschwärztes Präfix ausgegeben).
• Dies ist eine bewusste Token-Durchleitungseinrichtung. Stellen Sie sie immer über TLS bereit und lassen Sie vorzugsweise die eigene Bearer-Authentifizierung des Servers (--auth-token) als Gateway vor dem Multi-Mandanten-Verkehr aktiviert.

Beispiele

1. Mit der folgenden Anweisung

Comment "Hello MCP" on page "Getting started"

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

1. Ebenso führt die folgende Anweisung dazu, dass eine neue Seite mit dem Namen „Notion MCP“ zur übergeordneten Seite „Entwicklung“ 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

Bauen & Testen

npm run build
npm test

Ausführen

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

Änderungen lokal in Cursor testen:

1. Führen Sie den Befehl npm link vom Repository-Stammverzeichnis aus, um einen maschinenweiten symbolischen Link zum notion-mcp-server-Paket zu erstellen.
2. Fügen Sie den folgenden Konfigurationsausschnitt in die mcp.json von Cursor (oder einen anderen MCP-Client, mit dem Sie testen möchten) ein.
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