Claude Code + Notion MCP : Connecter ta Base de Connaissances à ton Code

Mis à jour le 27 mars 2026

Notion est devenu le cerveau de milliers d'équipes tech : specs produit, documentation, bases de données de bugs, roadmaps. Mais jusqu'ici, cette connaissance restait enfermée dans un onglet navigateur, déconnectée de ton code. Avec le MCP Server Notion, Claude Code accède directement à tes pages et bases de données Notion pendant qu'il code. Résultat : il lit tes specs avant d'implémenter, consulte ta documentation technique pour respecter les conventions, et peut même mettre à jour Notion quand le code évolue.

Si tu découvres les MCP Servers, commence par le guide complet des MCP Servers de Claude Code. Pour une vue d'ensemble de toutes les fonctionnalités, consulte le guide complet de Claude Code.

Pourquoi connecter Notion à Claude Code via MCP ?

Le problème classique : tu écris une spec produit détaillée dans Notion. Puis tu ouvres ton éditeur et tu demandes à Claude Code d'implémenter la feature. Mais Claude Code ne connaît pas ta spec. Tu dois copier-coller les passages pertinents, reformuler, donner du contexte. Et si la spec évolue ? Tu re-copies, tu re-colles. C'est du temps perdu et du risque d'incohérence.

Le MCP Notion élimine ce problème. Claude Code accède directement à Notion, en temps réel. Il lit la dernière version de tes specs, consulte tes bases de données, et utilise cette connaissance comme contexte pour coder.

Ce que le MCP Notion apporte concrètement

• Accès direct aux specs produit : Claude Code lit tes user stories, tes critères d'acceptation, tes wireframes textuels — sans que tu copies quoi que ce soit.
• Documentation technique synchronisée : conventions de nommage, architecture, décisions techniques (ADR) — tout est accessible en live.
• Requêtes sur tes bases de données : filtre les bugs par priorité, récupère les tasks d'un sprint, liste les endpoints d'une API documentée dans Notion.
• Écriture bidirectionnelle : Claude Code peut créer des pages, mettre à jour des statuts, documenter du code directement dans Notion.

Le vrai gain : ton code et ta documentation vivent dans le même flux de travail. Plus de va-et-vient entre navigateur et terminal. C'est du développement augmenté par l'IA, appliqué à la gestion de connaissances.

Comment installer et configurer le MCP Server Notion ?

L'installation nécessite trois étapes : créer une intégration Notion, partager les pages, puis configurer le MCP Server dans Claude Code.

Étape 1 : Créer une intégration Notion

L'intégration Notion est le pont entre l'API Notion et Claude Code. Voici comment la créer :

1. Va sur notion.so/my-integrations.
2. Clique sur New integration.
3. Donne un nom explicite : "Claude Code MCP".
4. Sélectionne le workspace Notion concerné.
5. Dans Capabilities, coche :
   • Read content (obligatoire).
   • Update content (si tu veux que Claude Code écrive dans Notion).
   • Insert content (pour créer de nouvelles pages).
6. Clique sur Submit.
7. Copie le Internal Integration Secret (commence par ntn_). Garde-le en sécurité.

Ce token ne doit jamais être commité dans un repo git. Stocke-le dans une variable d'environnement (NOTION_API_TOKEN) ou un gestionnaire de secrets.

Étape 2 : Partager les pages avec l'intégration

Point critique que beaucoup oublient : créer l'intégration ne suffit pas. Tu dois explicitement partager chaque page ou base de données avec ton intégration.

1. Ouvre la page Notion que tu veux rendre accessible.
2. Clique sur les trois points (...) en haut à droite.
3. Va dans Connexions (ou Connections).
4. Cherche et ajoute ton intégration "Claude Code MCP".
5. Confirme l'accès.

Astuce : si tu partages une page parent, toutes les sous-pages héritent automatiquement de l'accès. Partage la racine de ton espace documentation pour tout rendre accessible d'un coup.

Étape 3 : Configurer le MCP Server dans Claude Code

Deux méthodes possibles.

Méthode 1 : Via la commande CLI (recommandée)

claude mcp add notion -- npx @notionhq/notion-mcp-server --token=TON_TOKEN_NOTION

Cette commande ajoute automatiquement la configuration dans ton fichier settings.json.

Méthode 2 : Configuration manuelle dans settings.json

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_TOKEN": "ntn_ton_token_ici"
      }
    }
  }
}

Place cette configuration dans ~/.claude/settings.json pour un usage global, ou dans .claude/settings.json à la racine de ton projet pour un usage par projet. L'avantage de la variable d'environnement env : tu peux référencer un fichier .env local sans exposer le token.

Étape 4 : Vérifier la connexion

Lance Claude Code et teste :

claude
> Liste les pages Notion auxquelles tu as accès

Si Claude Code affiche tes pages et bases de données Notion, la connexion est opérationnelle. Si tu obtiens une erreur, vérifie trois choses : le token est valide, l'intégration est bien connectée aux pages, et le package npm est à jour.

Quels sont les cas d'usage concrets Notion + Claude Code ?

La connexion Notion + Claude Code ouvre des workflows que tu ne peux pas reproduire avec un simple copier-coller. Voici les cas d'usage les plus puissants.

Cas 1 : Implémenter une feature depuis une spec Notion

Tu as une page Notion avec la spec complète d'une feature : user stories, critères d'acceptation, maquettes textuelles, contraintes techniques. Au lieu de tout résumer dans un prompt, tu dis simplement :

> Lis la spec "Feature: Système de notifications" dans Notion
> et implémente-la en suivant l'architecture existante du projet.

Claude Code récupère la spec complète via le MCP, analyse la structure du projet, et génère le code en respectant les critères d'acceptation documentés. Si la spec contient des edge cases ou des contraintes, il les prend en compte sans que tu aies à les rappeler.

Cas 2 : Documentation technique comme contexte permanent

Ta doc technique dans Notion (conventions de code, architecture, patterns utilisés, décisions ADR) devient un contexte vivant pour Claude Code. Plutôt que de maintenir un fichier CLAUDE.md gigantesque, tu peux pointer vers ta documentation Notion :

> Avant de modifier ce module, consulte la page "Architecture Backend"
> dans Notion pour respecter les patterns établis.

L'avantage : ta documentation Notion évolue avec le projet, et Claude Code accède toujours à la dernière version. Plus de CLAUDE.md obsolète. Pour comprendre comment structurer ton fichier de configuration, consulte le guide du CLAUDE.md.

Cas 3 : Gestion de projet aware du code

Si tu gères tes tasks, bugs et sprints dans des bases de données Notion, Claude Code peut les requêter directement :

> Quels sont les bugs priorité haute non résolus dans la base "Bug Tracker" ?
> Corrige le premier bug de la liste.

Claude Code filtre la base de données Notion, identifie le bug, lit sa description et les étapes de reproduction, puis corrige le code correspondant. Il peut même mettre à jour le statut du bug dans Notion après correction.

Cas 4 : Générer de la documentation à partir du code

Le flux inverse fonctionne aussi. Tu viens de terminer une feature complexe et tu veux documenter :

> Analyse le module src/services/auth/ et crée une page de documentation
> dans la base "Documentation Technique" de Notion.
> Inclus : architecture, endpoints, modèles de données, exemples d'usage.

Claude Code lit le code, génère la documentation structurée, et la publie directement dans Notion. Plus d'excuse pour ne pas documenter.

Cas 5 : Synchronisation des API docs

Tu documentes tes endpoints API dans une base de données Notion (route, méthode, paramètres, réponses). Claude Code peut lire cette base pour :

• Générer des types TypeScript depuis les schémas documentés.
• Créer des tests d'intégration basés sur les exemples de réponses.
• Vérifier que le code implémente bien tous les endpoints documentés.
• Mettre à jour la documentation quand un endpoint change.

Comment structurer ta base Notion pour une utilisation optimale avec l'IA ?

La qualité de ce que Claude Code extrait de Notion dépend directement de la qualité de ta structuration. Un Notion bordélique donne des résultats bordéliques. Voici comment organiser pour maximiser l'efficacité.

Règle 1 : Une page = un concept

Évite les pages Notion de 5 000 mots qui mélangent spec, design, notes de réunion et TODOs. Découpe en pages atomiques :

• Specs produit : une page par feature, avec user stories et critères d'acceptation.
• Architecture : une page par module ou service, avec diagrammes et décisions.
• API : une base de données avec une entrée par endpoint.
• ADR : une page par décision technique, avec contexte et alternatives évaluées.

Claude Code performe mieux quand il peut accéder à une information précise plutôt que fouiller dans un document monolithique.

Règle 2 : Utilise les propriétés des bases de données

Les propriétés Notion (statut, priorité, assigné, tags, dates) sont des métadonnées que Claude Code peut utiliser pour filtrer et trier. Une base "Bug Tracker" avec les propriétés Priorité, Statut, Module permet des requêtes comme :

> Liste les bugs critiques du module "auth" qui sont en statut "À faire"

Sans propriétés structurées, Claude Code ne peut que lire du texte brut — il perd toute la puissance du filtrage.

Règle 3 : Nomme tes pages de façon explicite

"Notes réunion 15/03" ne dit rien à Claude Code. "Spec: Système de paiement Stripe - v2" est immédiatement compréhensible. Utilise un format de nommage cohérent :

• Spec: [Nom de la feature] pour les specifications.
• ADR-XXX: [Titre de la décision] pour les décisions d'architecture.
• Doc: [Nom du module] pour la documentation technique.
• API: [Route] pour les endpoints.

Règle 4 : Utilise les relations entre bases

Les relations Notion sont puissantes avec le MCP. Relie tes bases de données entre elles :

• Features → Tasks (une feature contient plusieurs tasks).
• Bugs → Features (un bug concerne une feature).
• Endpoints → Modules (un endpoint appartient à un module).

Claude Code peut suivre ces relations pour naviguer dans ton espace Notion de façon intelligente. "Quelles tasks restent pour la feature Paiement ?" devient une requête naturelle.

Règle 5 : Maintiens un index ou une page racine

Crée une page "Index Documentation" qui liste et relie toutes tes ressources. C'est le point d'entrée que tu donneras à Claude Code pour qu'il comprenne la structure de ta base de connaissances :

> Consulte la page "Index Documentation" dans Notion pour comprendre
> l'organisation de notre documentation technique.

Quelles sont les limites et alternatives au MCP Notion ?

Le MCP Notion est puissant, mais il a des contraintes qu'il faut connaître pour éviter les mauvaises surprises.

Limite 1 : La taille des pages

L'API Notion a une limite de blocs par requête. Les pages très longues (100+ blocs) nécessitent plusieurs requêtes séquentielles, ce qui ralentit la lecture. Solution : découpe tes pages longues en sous-pages. C'est de toute façon une meilleure pratique pour la lisibilité humaine aussi.

Limite 2 : Le contenu embarqué

Les embeds (Figma, Miro, Loom, Google Docs) dans Notion ne sont pas accessibles via l'API. Claude Code voit qu'il y a un embed, mais ne peut pas lire son contenu. Pour les maquettes Figma, utilise le MCP Figma dédié en complément.

Limite 3 : Les permissions granulaires

L'intégration Notion fonctionne au niveau du workspace. Tu ne peux pas donner accès à une seule colonne d'une base de données ou masquer certaines propriétés. Si tu as du contenu sensible (salaires, données clients), crée un workspace séparé ou ne partage pas ces pages avec l'intégration.

Limite 4 : La latence

Chaque accès Notion passe par l'API, ce qui ajoute de la latence par rapport à un fichier local. Pour du contexte statique qui change rarement (conventions, architecture), un fichier CLAUDE.md local reste plus rapide. Réserve le MCP Notion pour le contenu dynamique : specs en cours, bases de données, tasks actives.

Alternatives et compléments

Le MCP Notion n'est pas le seul moyen de connecter des sources de connaissances à Claude Code :

• CLAUDE.md : pour le contexte projet statique (conventions, stack, règles). Plus rapide, pas de dépendance réseau.
• MCP Figma : pour les designs et maquettes visuelles. Complémentaire au MCP Notion.
• MCP GitHub : pour les issues, PRs et discussions. Utile si ton tracking est sur GitHub plutôt que Notion.
• Skills Claude Code : pour encapsuler des workflows récurrents qui combinent Notion + code. Voir le guide des bonnes pratiques Claude Code.

Le setup idéal combine plusieurs MCP Servers : Notion pour les specs et la doc, Figma pour les designs, GitHub pour le code. Claude Code orchestre le tout de façon transparente. Pour une vue d'ensemble des serveurs disponibles, consulte le guide complet des MCP Servers.

La vraie puissance du MCP Notion n'est pas de lire une page. C'est de donner à Claude Code le même niveau de contexte qu'un développeur senior qui connaît le projet depuis 6 mois — les specs, l'architecture, les décisions passées, les bugs en cours. Tout ça, accessible en une requête.

Meydeey — Architecte IA & Automatisation

+110 entrepreneurs formés au Vibe Coding et à l'automatisation IA. Fondateur du Labo IA, +28K abonnés YouTube.

YouTube LinkedIn Communauté