# Notion MCP-Server

Ein [Model Context Protocol (MCP)](https://modelcontextprotocol.io)-Server, der **Notion mit Claude verbindet** – für Claude Desktop, Claude Code und jeden anderen MCP-fähigen Client.

Damit kann Claude direkt in deinem Notion-Workspace suchen, Seiten lesen und erstellen, Datenbanken abfragen und Inhalte bearbeiten.

## Funktionen (Tools)

| Tool | Beschreibung |
|---|---|
| `notion_search` | Workspace nach Seiten und Datenbanken durchsuchen |
| `notion_get_page` | Metadaten und Properties einer Seite abrufen |
| `notion_get_page_content` | Seiteninhalt als Markdown lesen (inkl. verschachtelter Blöcke) |
| `notion_create_page` | Neue Seite erstellen (als Unterseite oder Datenbank-Eintrag), Inhalt als Markdown |
| `notion_append_content` | Markdown-Inhalt an eine bestehende Seite anhängen |
| `notion_update_page` | Properties ändern, Seite archivieren/wiederherstellen |
| `notion_get_database` | Schema einer Datenbank abrufen (Properties, Optionen) |
| `notion_query_database` | Datenbank-Einträge abfragen (mit Filter und Sortierung) |
| `notion_create_database` | Neue Datenbank unter einer Seite anlegen |
| `notion_add_comment` | Kommentar zu einer Seite hinzufügen |
| `notion_get_comments` | Kommentare einer Seite lesen |
| `notion_list_users` | Benutzer des Workspace auflisten |

Alle Tools akzeptieren sowohl Notion-IDs als auch vollständige Notion-URLs.

## Voraussetzungen

- Node.js 18 oder neuer
- Ein Notion-Konto mit einem Workspace

## 1. Notion-Integration erstellen

1. Öffne <https://www.notion.so/profile/integrations>
2. Klicke auf **„Neue Integration“** und gib ihr einen Namen (z. B. „Claude“)
3. Wähle deinen Workspace aus und speichere
4. Kopiere den **Internal Integration Token** (beginnt mit `ntn_` oder `secret_`)

**Wichtig:** Die Integration sieht nur Seiten, die du explizit freigibst. Öffne dazu in Notion die gewünschte Seite (oder eine übergeordnete Seite), klicke oben rechts auf **`···` → Verbindungen → Verbindung hinzufügen** und wähle deine Integration aus. Unterseiten erben die Freigabe automatisch.

## 2. Server installieren und bauen

```bash
git clone https://github.com/loberkehr-art/Code-mcp-Notion-.git
cd Code-mcp-Notion-
npm install
npm run build
```

## 3. Mit Claude verbinden

### Claude Desktop

Trage den Server in die Konfigurationsdatei ein:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/Code-mcp-Notion-/dist/index.js"],
      "env": {
        "NOTION_API_KEY": "ntn_dein_token_hier"
      }
    }
  }
}
```

Danach Claude Desktop neu starten. Die Notion-Tools erscheinen im Tool-Menü (🔨).

### Claude Code (CLI)

```bash
claude mcp add notion \
  --env NOTION_API_KEY=ntn_dein_token_hier \
  -- node /absoluter/pfad/zu/Code-mcp-Notion-/dist/index.js
```

## Beispiele

Sobald der Server verbunden ist, kannst du Claude z. B. bitten:

- *„Suche in Notion nach meinen Meeting-Notizen“*
- *„Lies die Seite ‚Projektplan‘ und fasse sie zusammen“*
- *„Erstelle in der Aufgaben-Datenbank einen Eintrag ‚Steuererklärung‘ mit Status ‚Offen‘“*
- *„Zeige alle Einträge der Datenbank, deren Status ‚In Arbeit‘ ist“*
- *„Hänge diese Zusammenfassung an meine Wochennotizen an“*

## Entwicklung

```bash
npm run dev      # Server direkt aus TypeScript starten (tsx)
npm run watch    # TypeScript im Watch-Modus kompilieren
```

Der Server kommuniziert über **stdio** (Standard-Ein-/Ausgabe) und loggt Statusmeldungen nach stderr, damit das MCP-Protokoll auf stdout ungestört bleibt.

### Projektstruktur

```
src/
├── index.ts       # MCP-Server und Tool-Definitionen
├── markdown.ts    # Konvertierung Markdown ⇄ Notion-Blöcke
└── properties.ts  # Lesen und Schreiben von Seiten-Properties
```

## Hinweise & Grenzen

- Die Notion-API erlaubt maximal 100 Blöcke pro Schreibvorgang – längere Inhalte werden automatisch in mehreren Aufrufen angehängt.
- Neue Seiten können nur unterhalb einer bestehenden Seite oder Datenbank angelegt werden (API-Einschränkung von Notion).
- Berechnete Property-Typen (`formula`, `rollup`, `created_time`, …) sind nur lesbar, nicht beschreibbar.
- Der Token gehört in die Umgebungsvariable `NOTION_API_KEY` – niemals ins Repository committen (`.env` ist in `.gitignore`).

## Lizenz

MIT