Notion MCP

Serveur MCP Notion

[!NOTE]

Nous avons présenté Notion MCP, un serveur MCP distant avec les améliorations suivantes :

• Installation facile via OAuth standard. Plus besoin de manipuler du JSON ou des jetons API.
• Outils puissants adaptés aux agents IA, y compris l'édition de pages en Markdown. Ces outils sont conçus pour optimiser la consommation de jetons.

Pour en savoir plus et démarrer, consultez la documentation Notion MCP.

Nous donnons la priorité et fournissons un support actif uniquement pour Notion MCP (distant). Par conséquent :

• Nous pourrions abandonner ce dépôt de serveur MCP local à l'avenir.
• Les tickets et les pull requests ici ne sont pas surveillés activement.
• Veuillez ne pas soumettre de tickets concernant le MCP distant ici ; contactez plutôt le support Notion.

Ce projet implémente un serveur MCP pour l'API Notion.

---

⚠️ Changements majeurs de la version 2.0.0

La version 2.0.0 migre vers l'API Notion 2025-09-03 qui introduit les sources de données comme abstraction principale pour les bases de données.

Ce qui a changé

Outils supprimés (3) :

• post-database-query - remplacé par query-data-source
• update-a-database - remplacé par update-a-data-source
• create-a-database - remplacé par create-a-data-source

Nouveaux outils (7) :

• query-data-source - Interroger une source de données (base de données) avec des filtres et des tris
• retrieve-a-data-source - Obtenir les métadonnées et le schéma d'une source de données
• update-a-data-source - Mettre à jour les propriétés d'une source de données
• create-a-data-source - Créer une nouvelle source de données
• list-data-source-templates - Lister les modèles disponibles dans une source de données
• move-page - Déplacer une page vers un emplacement parent différent
• retrieve-a-database - Obtenir les métadonnées de la base de données, y compris ses identifiants de source de données

Changements de paramètres :

• Toutes les opérations de base de données utilisent désormais data_source_id au lieu de database_id
• Les valeurs de filtre de recherche sont passées de ["page", "database"] à ["page", "data_source"]
• La création de page prend désormais en charge les parents page_id et database_id (pour les sources de données)

Dois-je migrer ?

Aucune modification de code requise. Les outils MCP sont découverts automatiquement au démarrage du serveur. Lorsque vous passez à la v2.0.0, les clients IA verront automatiquement les nouveaux noms d'outils et paramètres. Les anciens outils de base de données ne sont plus disponibles.

Si vous avez des noms d'outils codés en dur ou des invites qui font référence aux anciens outils de base de données, mettez-les à jour pour utiliser les nouveaux outils de source de données :

Ancien outil (v1.x)	Nouvel outil (v2.0)	Changement de paramètre
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	Aucun changement (utilise parent.page_id)

Remarque : retrieve-a-database est toujours disponible et renvoie les métadonnées de la base de données, y compris la liste des identifiants de source de données. Utilisez retrieve-a-data-source pour obtenir le schéma et les propriétés d'une source de données spécifique.

Nombre total d'outils désormais : 22 (contre 19 dans la v1.x)

---

Contenu de page en Markdown

Le serveur expose deux outils pour travailler avec le contenu des pages en Markdown enrichi au lieu de JSON de blocs, ce qui est nettement plus économe en jetons pour les agents IA :

• retrieve-page-markdown — Lire le contenu complet d'une page en Markdown (GET /v1/pages/{page_id}/markdown). Passez include_transcript: true pour inclure les transcriptions de notes de réunion.
• update-page-markdown — Modifier le contenu d'une page avec du Markdown (PATCH /v1/pages/{page_id}/markdown). Préférez replace_content pour écraser toute la page, ou update_content pour des modifications ciblées de type rechercher-remplacer.

Ces points de terminaison nécessitent la version d'API Notion 2026-03-11. Le serveur source désormais l'en-tête Notion-Version par opération à partir de la spécification OpenAPI, de sorte que ces outils utilisent 2026-03-11 tandis que le reste de l'API continue d'utiliser 2025-09-03 — aucune configuration nécessaire. Si vous définissez vous-même Notion-Version via OPENAPI_MCP_HEADERS, votre valeur prévaut pour chaque outil.

---

Installation

1. Configuration de l'intégration dans Notion

Allez sur https://www.notion.so/profile/integrations et créez une nouvelle intégration interne ou sélectionnez-en une existante.

Bien que nous limitions la portée de l'API Notion exposée (par exemple, vous ne pourrez pas supprimer des bases de données via MCP), il existe un risque non nul pour les données de l'espace de travail en les exposant aux LLM. Les utilisateurs soucieux de la sécurité peuvent vouloir configurer davantage les Capacités de l'intégration.

Par exemple, vous pouvez créer un jeton d'intégration en lecture seule en donnant uniquement l'accès "Lire le contenu" depuis l'onglet "Configuration" :

2. Connexion du contenu à l'intégration

Assurez-vous que les pages et bases de données pertinentes sont connectées à votre intégration.

Pour ce faire, visitez l'onglet Accès dans les paramètres de votre intégration interne. Modifiez l'accès et sélectionnez les pages que vous souhaitez utiliser.

Alternativement, vous pouvez accorder l'accès aux pages individuellement. Vous devrez visiter la page cible, cliquer sur les 3 points, et sélectionner "Connecter à l'intégration".

3. Ajout de la configuration MCP à votre client

Utilisation de npm

Cursor & Claude

Ajoutez ce qui suit à votre .cursor/mcp.json ou claude_desktop_config.json (MacOS : ~/Library/Application\ Support/Claude/claude_desktop_config.json)

Option 1 : Utilisation de NOTION_TOKEN (recommandé)

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

Option 2 : Utilisation de OPENAPI_MCP_HEADERS (pour les cas d'utilisation avancés)

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

Zed

Ajoutez ce qui suit à votre settings.json

{
  "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

Utilisez le Copilot CLI pour ajouter interactivement le serveur MCP :

/mcp add

Alternativement, créez ou modifiez le fichier de configuration ~/.copilot/mcp-config.json et ajoutez :

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

Pour plus d'informations, consultez la documentation Copilot CLI.

Utilisation de Docker

Il existe deux options pour exécuter le serveur MCP avec Docker :

Option 1 : Utilisation de l'image officielle Docker Hub

Ajoutez ce qui suit à votre .cursor/mcp.json ou claude_desktop_config.json

Utilisation de NOTION_TOKEN (recommandé) :

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

Utilisation de OPENAPI_MCP_HEADERS (pour les cas d'utilisation avancés) :

{
  "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\"}"
      }
    }
  }
}

Cette approche :

• Utilise l'image officielle Docker Hub
• Gère correctement l'échappement JSON via les variables d'environnement
• Fournit une méthode de configuration plus fiable

Option 2 : Construction de l'image Docker localement

Vous pouvez également construire et exécuter l'image Docker localement. D'abord, construisez l'image Docker :

docker compose build

Ensuite, ajoutez ce qui suit à votre .cursor/mcp.json ou claude_desktop_config.json

Utilisation de NOTION_TOKEN (recommandé) :

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

Utilisation de OPENAPI_MCP_HEADERS (pour les cas d'utilisation avancés) :

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

N'oubliez pas de remplacer ntn_**** par votre secret d'intégration. Trouvez-le dans l'onglet de configuration de votre intégration :

Options de transport

Le serveur MCP Notion prend en charge deux modes de transport :

Transport STDIO (par défaut)

Le mode de transport par défaut utilise l'entrée/sortie standard pour la communication. C'est le transport MCP standard utilisé par la plupart des clients comme Claude Desktop.

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

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

Transport HTTP Streamable

Pour les applications web ou les clients qui préfèrent la communication HTTP, vous pouvez utiliser le transport HTTP Streamable :

# 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"

Lors de l'utilisation du transport HTTP Streamable, le serveur sera disponible à http://127.0.0.1:<port>/mcp par défaut.

Authentification

Le transport HTTP Streamable nécessite une authentification par jeton porteur pour la sécurité. Vous avez trois options :

Option 1 : Jeton auto-généré (uniquement pour le développement)

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

Le serveur générera un jeton aléatoire sécurisé et l'écrira dans un fichier avec des permissions restreintes :

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

Option 2 : Jeton personnalisé via la ligne de commande (recommandé pour la production)

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

Option 3 : Jeton personnalisé via une variable d'environnement (recommandé pour la production)

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

L'argument de ligne de commande --auth-token prend le pas sur la variable d'environnement AUTH_TOKEN si les deux sont fournis.

Option non sécurisée : désactiver l'authentification HTTP

Vous pouvez désactiver l'authentification par jeton porteur uniquement avec le drapeau non sécurisé explicite :

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

AVERTISSEMENT : --unsafe-disable-auth n'est pas sécurisé. Le serveur peut être accessible aux pages que vous visitez via le rebinding DNS. Utilisez-le uniquement sur un réseau isolé.

Lorsque l'authentification est désactivée, le serveur active la protection contre le rebinding DNS en vérifiant les en-têtes Host et Origin par rapport à l'hôte local configuré et aux hôtes de bouclage. L'ancien drapeau --disable-auth est toujours accepté comme alias obsolète, mais il affichera un avertissement.

Effectuer des requêtes HTTP

Toutes les requêtes vers le transport HTTP Streamable doivent inclure le jeton porteur dans l'en-tête Authorization :

# 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

Remarque : Assurez-vous de définir soit la variable d'environnement NOTION_TOKEN (recommandé) soit la variable d'environnement OPENAPI_MCP_HEADERS avec votre jeton d'intégration Notion lors de l'utilisation de l'un ou l'autre mode de transport.

Servir plusieurs intégrations (passage de jeton par requête)

Par défaut, le serveur s'authentifie auprès de Notion avec un seul jeton intégré au démarrage, ce qui verrouille un déploiement à une seule intégration Notion. Pour permettre à un seul déploiement de servir plusieurs intégrations, activez le passage de jeton afin que chaque client fournisse son propre jeton d'intégration Notion par connexion :

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

Les clients envoient ensuite leur jeton Notion lors de la requête initialize en utilisant l'en-tête dédié Notion-Token :

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

Comment le jeton est résolu pour chaque connexion, dans l'ordre :

1. L'en-tête Notion-Token (préféré — non ambigu, et fonctionne avec l'authentification de passerelle Authorization propre au serveur). S'il est présent, il doit s'agir d'un jeton Notion valide, sinon la requête est rejetée avec 401.
2. Authorization: Bearer ntn_**** — uniquement lorsque l'authentification porteur propre au serveur est désactivée (--unsafe-disable-auth), de sorte que l'en-tête soit libre de transporter le jeton Notion directement.
3. Sinon, le jeton d'environnement de démarrage (NOTION_TOKEN / OPENAPI_MCP_HEADERS), s'il est défini, afin que le passage de jeton et une intégration par défaut puissent coexister sur un seul déploiement.

Remarques :

• Seules les valeurs avec un préfixe de jeton Notion (ntn_, legacy secret_) sont traitées comme des jetons Notion, de sorte que le secret de passerelle du serveur et le jeton Notion d'un locataire n'entrent jamais en collision.
• Chaque jeton est lié à sa session MCP ; les jetons ne sont jamais journalisés (seul un préfixe expurgé est émis).
• Il s'agit d'une configuration délibérée de passage de jeton. Déployez-la toujours sur TLS, et préférez garder l'authentification porteur propre au serveur (--auth-token) activée comme passerelle devant le trafic multi-locataire.

Exemples

1. En utilisant l'instruction suivante

Comment "Hello MCP" on page "Getting started"

L'IA planifiera correctement deux appels API, v1/search et v1/comments, pour accomplir la tâche

1. De même, l'instruction suivante résultera en une nouvelle page nommée "Notion MCP" ajoutée à la page parente "Development"

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

1. Vous pouvez également référencer directement l'identifiant de contenu

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Développement

Construction & test

npm run build
npm test

Exécution

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

Tester les changements localement dans Cursor :

1. Exécutez la commande npm link depuis la racine du dépôt pour créer un lien symbolique global vers le paquet notion-mcp-server.
2. Fusionnez l'extrait de configuration ci-dessous dans le mcp.json de Cursor (ou autre client MCP avec lequel vous voulez tester).
3. (Nettoyage) exécutez npm unlink depuis la racine du dépôt.

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

Publication

npm login
npm publish --access public