Notion in Claude nutzen (MCP)

Zielgruppe: primär IT-Dev/Architektur und DevOps (CI/CD · Cloud-Sessions); sekundär Anwender, die Claude Desktop am Arbeitsplatz nutzen.

Kernaussage. Taktano bindet Notion über einen MCP-Server (Model Context Protocol) an Claude an. Das Repo liefert eine eingecheckte .mcp.json → Claude Code (lokal und in der Cloud) findet den Notion-Server automatisch; Claude Desktop wird einmalig pro Arbeitsplatz konfiguriert. Authentifiziert wird über ein Notion-Integrations-Token (NOTION_TOKEN), das als Umgebungs-Variable/Secret bereitsteht — niemals im Repo.

Warum so. Ein Token-basierter, eingecheckter MCP-Eintrag funktioniert auch in headless Cloud-Sessions (kein interaktiver Browser-OAuth-Flow nötig) und hält das Geheimnis aus dem Code heraus (${NOTION_TOKEN}-Expansion statt Klartext). Der Zugriff bleibt least-privilege: Claude sieht in Notion nur, was der Integration explizit freigegeben wurde.

True-North-Bezug. Indirekt — die Integration verkürzt den Weg von Repo-Wissen zu Notion-Arbeitsflächen (Doku/Tasks) und stützt damit schnelle, korrekte Antworten rund um Stand & Planung. Kein Laufzeit-/Produktivpfad von Taktano selbst (reines Contributor-Tooling).

---

1. Überblick (wer konfiguriert was)

Client	Konfigurationsort	Token kommt aus
Claude Code (lokal)	/.mcp.json (im Repo)	Shell-Umgebung (export NOTION_TOKEN=…)
Claude Code (Cloud/Web)	/.mcp.json (im Repo)	Umgebungs-Secret der Cloud-Umgebung
Claude Desktop	claude_desktop_config.json (pro Gerät, nicht im Repo)	Eintrag in dieser Datei oder Connector-OAuth

---

2. Voraussetzung: Notion-Integration + Token

1. Unter https://www.notion.so/profile/integrations eine interne Integration anlegen.
2. Capabilities wählen: für reines Lesen nur Read content; für Schreiben zusätzlich Insert/Update content (least privilege — nur geben, was gebraucht wird).
3. Den Internal Integration Secret kopieren (beginnt mit ntn_…). Das ist der NOTION_TOKEN.
4. Bereich freigeben (wichtig): In Notion eine Container-Seite anlegen (z. B. 🤖 Claude-Bereich), alles Relevante darunter ablegen und die Integration einmal mit dieser Seite verbinden (••• → Connections → <Integration>). Die Freigabe vererbt sich auf alle Unterseiten → ein Bereich statt jede Seite einzeln. Alles außerhalb bleibt privat.

Sicherheit/Compliance (DE/AT/CH). Inhalte, die Claude liest, werden vom Modell verarbeitet. Nur freigeben, was dafür vorgesehen ist; das Token ist ein Geheimnis (Behandlung wie ein Passwort, Rotation bei Verdacht). Siehe docs/betrieb/Compliance.md / docs/betrieb/Risikoregister.md.

---

3. Claude Code — lokal

Die eingecheckte .mcp.json genügt; nur das Token muss in der Umgebung stehen, bevor Claude Code startet:

export NOTION_TOKEN=ntn_dein_token   # z. B. in ~/.zshrc / ~/.bashrc oder via direnv
claude                                # im Repo-Verzeichnis starten

Beim ersten Start fragt Claude Code, ob dem projekt-skopierten MCP-Server vertraut werden soll → bestätigen. Prüfen mit /mcp (Status connected + gelistete Notion-Tools).

Token nie in eine eingecheckte Datei schreiben. .env/.dev.vars sind bereits via .gitignore ausgeschlossen — falls du dort ablegst, lade es vor dem Start in die Shell.

---

4. Claude Code — Cloud / Web

In der Cloud läuft die Session headless → der Token kommt aus einem Umgebungs-Secret der Cloud-Umgebung (nicht aus einer lokalen Shell, kein Browser-OAuth):

1. In der Cloud-Umgebung (Claude-Code-Web-Einstellungen) ein Secret NOTION_TOKEN mit dem ntn_…-Wert hinterlegen.
2. Die eingecheckte .mcp.json wird beim Start gelesen; ${NOTION_TOKEN} wird aus dem Secret expandiert. Status via /mcp prüfen.

Hinweis OAuth vs. Token. Der gehostete OAuth-Server (https://mcp.notion.com/mcp) ist lokal am bequemsten, aber der Browser-Login ist in headless Cloud-Sessions oft nicht durchführbar — deshalb hier bewusst die Token-Variante.

---

5. Claude Desktop (pro Arbeitsplatz)

Claude Desktop nutzt nicht die Repo-.mcp.json, sondern eine geräte-lokale Datei. Zwei Wege:

A) Connector (OAuth, am einfachsten): Settings → Connectors → Add custom connector → URL https://mcp.notion.com/mcp → Browser-Login.

B) Token-basiert (claude_desktop_config.json):

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

Datei-Ort: macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json. Danach Claude Desktop neu starten.

---

6. Was geht damit (Beispiele)

• Lesen/Suchen: „Finde im Claude-Bereich alle Seiten zu Onboarding", Datenbank-Einträge filtern, Seiteninhalte zusammenfassen.
• Erstellen/Bearbeiten: neue Seite aus Repo-Doku anlegen, Datenbank-Felder (Status/Tags) aktualisieren, Kommentare ergänzen — sofern die Integration Insert/Update-Capability hat.

Grenzen. Nur freigegebene Seiten/DBs sind sichtbar; Schreibzugriff verändert echtes Notion — für Experimente einen Test-Bereich nutzen.

---

7. Troubleshooting

Symptom	Ursache / Fix
/mcp zeigt failed / kein Notion	NOTION_TOKEN nicht in der Umgebung → setzen, Claude neu starten
Notion-Tools da, aber „not found"/leer	Seite/DB nicht mit der Integration verbunden → in Notion freigeben
Schreiben schlägt fehl	Integration hat keine Insert/Update-Capability → in Notion nachziehen
npx-Download scheitert (Cloud-Netz)	Netzwerk-Policy der Umgebung erlaubt npm nicht → Policy prüfen (Doku: Claude-Code-on-the-web)

---

↩ Zurück zur Doku-Landkarte · Lesepfade · Register (alle OPs)