Notion MCP

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

Serveur Notion MCP

[!NOTE]

Pour une expérience optimale, utilisez Remote Notion MCP, notre serveur MCP hébergé officiellement. Ce dépôt est une implémentation distincte de serveur MCP auto-hébergé qui n'est plus activement maintenue ni prise en charge. Veuillez utiliser Remote Notion MCP à la place. Il est spécialement conçu pour offrir aux agents IA des résultats plus rapides en utilisant beaucoup moins de jetons.

Remote Notion MCP peut rechercher sémantiquement dans votre espace de travail et les applications connectées, lire et modifier des pages en Markdown, et ne renvoyer que le contexte le plus pertinent. Cela signifie moins de temps d'attente, moins d'utilisation de la fenêtre de contexte et des coûts de jetons réduits. Il utilise également OAuth et respecte automatiquement les autorisations Notion existantes de chaque utilisateur—sans jetons API, configuration JSON, partage manuel de pages ou serveur local à maintenir.

Fonctionnalité	Remote Notion MCP	Ce projet (local)
Expérience hébergée et rapide	✅	S'exécute et se met à jour localement
Réponses économes en jetons	✅	Limitée
Outils puissants adaptés aux agents IA	✅	Outils de base dérivés de l'API
Recherche sémantique dans votre espace de travail Notion	✅	Recherche par mots-clés uniquement
Recherche AI Connector dans les applications connectées	✅	Non disponible
Lecture et modification de pages natives en Markdown	✅	Limitée à deux outils de contenu de page
Configuration OAuth transparente	✅	Configuration manuelle du jeton et du JSON
Respecte les autorisations Notion existantes de chaque utilisateur	✅	Autorisations d'intégration manuelles et partage de pages
Support actif et améliorations continues	✅	Non activement pris en charge

En savoir plus et commencer avec la documentation Remote Notion MCP.

Nous donnons la priorité à Remote Notion MCP et ne fournissons un support actif que pour celui-ci. Par conséquent :

• Nous pourrions retirer ce dépôt de serveur MCP local à l'avenir.
• Les problèmes et les demandes de tirage ici ne sont pas activement surveillés.
• Veuillez ne pas signaler de problèmes liés au MCP distant ici ; contactez plutôt le support Notion.

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

---

⚠️ Changements de rupture 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 d'une 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 référencent les 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 maintenant : 22 (était de 19 en v1.x)

---

Contenu de page en Markdown

Le serveur expose deux outils pour travailler avec le contenu de page 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 intégrer les transcriptions de notes de réunion.
• update-page-markdown — Modifier le contenu d'une page avec 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 recherche et remplacement.

Ces points de terminaison nécessitent la version 2026-03-11 de l'API Notion. Le serveur source désormais l'en-tête Notion-Version par opération à partir de la spécification OpenAPI, donc ces outils utilisent 2026-03-11 tandis que le reste de l'API continue d'utiliser 2025-09-03 — aucune configuration requise. Si vous définissez Notion-Version vous-même 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 CLI Copilot 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 du CLI Copilot.

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 Notion MCP 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 des raisons de 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 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 a priorité sur la variable d'environnement AUTH_TOKEN si les deux sont fournis.

Option dangereuse : désactiver l'authentification HTTP

Vous pouvez désactiver l'authentification par jeton porteur uniquement avec l'indicateur explicitement dangereux :

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

AVERTISSEMENT : --unsafe-disable-auth est dangereux. 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 indicateur --disable-auth est toujours accepté comme alias obsolète, mais il affichera un avertissement.

Effectuer des requêtes HTTP

Toutes les requêtes au 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 (transmission 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 sur une seule intégration Notion. Pour permettre à un seul déploiement de servir plusieurs intégrations, activez la transmission 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 sur 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é — sans ambiguïté, et fonctionne en parallèle de l'authentification de passerelle Authorization du serveur). S'il est présent, il doit être un jeton Notion valide, sinon la requête est rejetée avec 401.
2. Authorization: Bearer ntn_**** — uniquement lorsque l'authentification par porteur du serveur est désactivée (--unsafe-disable-auth), afin 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 la transmission 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_, hérité secret_) sont traitées comme des jetons Notion, donc 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 masqué est émis).
• Il s'agit d'une configuration de transmission de jeton délibérée. Déployez-la toujours sur TLS, et préférez garder l'authentification par porteur du serveur (--auth-token) activée comme passerelle devant le trafic multi-locataires.

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 aboutira à 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 du contenu

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Développement

Compilation et tests

npm run build
npm test

Exécution

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

Tester les modifications localement dans Cursor :

1. Exécutez la commande npm link depuis la racine du dépôt pour créer un lien symbolique global à la machine vers le package notion-mcp-server.
2. Fusionnez l'extrait de configuration ci-dessous dans le fichier mcp.json de Cursor (ou tout autre client MCP avec lequel vous souhaitez 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