Serveurs MCP : Créez Votre Premier Serveur en 20 Minutes

# Vérifier la version Python python --version # → Python 3.11.8 (ou supérieur) pip --version # → pip 24.0 # Si Python n'est pas installé : # macOS : brew install python@3.11 # Ubuntu : sudo apt install python3.11 python3.11-venv # Windows : télécharger depuis python.org

# Créer le dossier du projet mkdir notion-mcp-serveur cd notion-mcp-serveur # Créer l'environnement virtuel (isole les dépendances) python -m venv venv # L'activer source venv/bin/activate # macOS / Linux # venv\Scripts\activate.bat # Windows # Vérifier l'activation — le prompt doit afficher (venv) which python # → /chemin/vers/notion-mcp-serveur/venv/bin/python

# Installer le SDK MCP avec support FastMCP pip install "mcp[cli]>=1.4.0" # Installer le client Notion pip install notion-client>=2.2.1 # Vérifier pip show mcp # → Name: mcp # → Version: 1.4.x pip show notion-client # → Name: notion-client # → Version: 2.2.x

Pourquoi FastMCP ? Le SDK officiel MCP Python propose deux APIs : la classe bas niveau Server (verbeux mais flexible) et FastMCP (basé sur des décorateurs, 3× moins de code). Ce tutoriel utilise FastMCP. Les deux sont production-ready.

Important : Claude ne peut accéder qu'aux pages que vous partagez explicitement avec l'intégration. C'est voulu — cela évite l'accès accidentel à des notes privées. Partagez uniquement les bases de données ou pages que vous souhaitez que Claude lise et modifie.

# serveur.py import asyncio import os from mcp.server.fastmcp import FastMCP from notion_client import AsyncClient # Initialiser le serveur FastMCP mcp = FastMCP("Assistant Notion") # Initialiser le client Notion # Définissez la variable d'environnement NOTION_API_KEY avant de lancer notion = AsyncClient(auth=os.environ["NOTION_API_KEY"]) # ── OUTIL 1 : Rechercher des pages ──────────────────────────────────────────── @mcp.tool() async def rechercher_notion(requete: str) -> str: """Chercher des pages et bases de données dans Notion par mot-clé. Args: requete: Le terme de recherche (ex : "notes réunion", "suivi projets") Returns: Une liste des pages correspondantes avec titre et URL. """ response = await notion.search(query=requete, page_size=10) if not response["results"]: return f"Aucun résultat pour '{requete}'" lignes = [f"Trouvé {len(response['results'])} résultat(s) pour '{requete}' :\n"] for item in response["results"]: type_item = item["object"] if type_item == "page": titre = _obtenir_titre_page(item) url = item.get("url", "") lignes.append(f"- [Page] {titre}\n URL : {url}\n ID : {item['id']}") elif type_item == "database": titre = item.get("title", [{}])[0].get("plain_text", "Sans titre") url = item.get("url", "") lignes.append(f"- [Base] {titre}\n URL : {url}\n ID : {item['id']}") return "\n".join(lignes) # ── OUTIL 2 : Lire une page ─────────────────────────────────────────────────── @mcp.tool() async def lire_page(page_id: str) -> str: """Lire le contenu complet d'une page Notion. Args: page_id: L'identifiant de la page Notion (issu des résultats de recherche ou de l'URL) Returns: Le titre de la page et tout son contenu textuel, bloc par bloc. """ # Nettoyer l'ID (supprimer les tirets si besoin) page_id = page_id.replace("-", "") # Récupérer les métadonnées de la page page = await notion.pages.retrieve(page_id=page_id) titre = _obtenir_titre_page(page) # Récupérer tous les blocs (contenu de la page) blocs_response = await notion.blocks.children.list(block_id=page_id) blocs = blocs_response["results"] lignes = [f"# {titre}\n"] for bloc in blocs: type_bloc = bloc["type"] if type_bloc == "paragraph": texte = _extraire_texte_riche(bloc["paragraph"]["rich_text"]) if texte: lignes.append(texte) elif type_bloc in ("heading_1", "heading_2", "heading_3"): niveau = type_bloc[-1] texte = _extraire_texte_riche(bloc[type_bloc]["rich_text"]) lignes.append(f"{'#' * int(niveau)} {texte}") elif type_bloc == "bulleted_list_item": texte = _extraire_texte_riche(bloc["bulleted_list_item"]["rich_text"]) lignes.append(f"- {texte}") elif type_bloc == "numbered_list_item": texte = _extraire_texte_riche(bloc["numbered_list_item"]["rich_text"]) lignes.append(f"• {texte}") elif type_bloc == "to_do": texte = _extraire_texte_riche(bloc["to_do"]["rich_text"]) coche = "✅" if bloc["to_do"]["checked"] else "☐" lignes.append(f"{coche} {texte}") elif type_bloc == "code": texte = _extraire_texte_riche(bloc["code"]["rich_text"]) lang = bloc["code"].get("language", "") lignes.append(f"\n```{lang}\n{texte}\n```\n") return "\n".join(lignes) # ── OUTIL 3 : Créer une nouvelle page ──────────────────────────────────────── @mcp.tool() async def creer_page( parent_id: str, titre: str, contenu: str, ) -> str: """Créer une nouvelle page dans une base Notion ou comme sous-page. Args: parent_id: ID de la base ou page parente titre: Titre de la nouvelle page contenu: Contenu textuel de la page (texte brut, double saut de ligne pour les paragraphes) Returns: Confirmation avec l'URL de la page créée. """ parent_id = parent_id.replace("-", "") # Déterminer si le parent est une base ou une page try: await notion.databases.retrieve(database_id=parent_id) parent = {"database_id": parent_id} propriete_titre = "Name" # Propriété titre par défaut dans les bases except Exception: parent = {"page_id": parent_id} propriete_titre = "title" # Construire les blocs à partir du contenu blocs = [] for paragraphe in contenu.split("\n\n"): paragraphe = paragraphe.strip() if paragraphe: blocs.append({ "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{"type": "text", "text": {"content": paragraphe}}] } }) # Créer la page response = await notion.pages.create( parent=parent, properties={ propriete_titre: { "title": [{"type": "text", "text": {"content": titre}}] } }, children=blocs, ) url = response.get("url", "") return f"✅ Page '{titre}' créée avec succès.\nURL : {url}\nID : {response['id']}" # ── OUTIL 4 : Lister les bases de données ──────────────────────────────────── @mcp.tool() async def lister_bases() -> str: """Lister toutes les bases Notion partagées avec cette intégration. Returns: Noms et IDs de toutes les bases accessibles. """ response = await notion.search( filter={"value": "database", "property": "object"}, page_size=20 ) if not response["results"]: return "Aucune base trouvée. Assurez-vous d'avoir partagé au moins une base avec l'intégration." lignes = [f"Trouvé {len(response['results'])} base(s) :\n"] for db in response["results"]: titre = db.get("title", [{}])[0].get("plain_text", "Sans titre") db_id = db["id"] url = db.get("url", "") lignes.append(f"- {titre}\n ID : {db_id}\n URL : {url}") return "\n".join(lignes) # ── OUTIL 5 : Ajouter du contenu à une page ────────────────────────────────── @mcp.tool() async def ajouter_a_page(page_id: str, contenu: str) -> str: """Ajouter du contenu textuel à une page Notion existante. Args: page_id: ID de la page à modifier contenu: Texte à ajouter (double saut de ligne pour les paragraphes) Returns: Message de confirmation. """ page_id = page_id.replace("-", "") blocs = [] for paragraphe in contenu.split("\n\n"): paragraphe = paragraphe.strip() if paragraphe: blocs.append({ "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{"type": "text", "text": {"content": paragraphe}}] } }) if not blocs: return "Aucun contenu à ajouter." await notion.blocks.children.append(block_id=page_id, children=blocs) return f"✅ {len(blocs)} paragraphe(s) ajouté(s) à la page {page_id}" # ── Fonctions utilitaires ───────────────────────────────────────────────────── def _obtenir_titre_page(page: dict) -> str: """Extraire le titre d'un objet page Notion.""" properties = page.get("properties", {}) for prop in properties.values(): if prop.get("type") == "title": rich_text = prop.get("title", []) if rich_text: return rich_text[0].get("plain_text", "Sans titre") return "Sans titre" def _extraire_texte_riche(rich_text_array: list) -> str: """Concaténer le texte brut d'un tableau rich_text Notion.""" return "".join(item.get("plain_text", "") for item in rich_text_array) # ── Point d'entrée ──────────────────────────────────────────────────────────── if __name__ == "__main__": mcp.run()

# macOS ~/Library/Application Support/Claude/claude_desktop_config.json # Windows %APPDATA%\Claude\claude_desktop_config.json # Linux ~/.config/Claude/claude_desktop_config.json # Si le fichier n'existe pas, créez-le # (Claude Desktop le crée normalement au premier lancement)

{ "mcpServers": { "assistant-notion": { "command": "/chemin/absolu/notion-mcp-serveur/venv/bin/python", "args": ["/chemin/absolu/notion-mcp-serveur/serveur.py"], "env": { "NOTION_API_KEY": "secret_VOTRE_CLE_API_NOTION_ICI" } } } }

Utilisez des chemins absolus. Claude Desktop lance le serveur comme un sous-processus — les chemins relatifs comme ./venv/bin/python ne fonctionneront pas. Exécutez which python (avec le venv activé) et pwd pour obtenir les chemins absolus corrects.

# Dans votre terminal, avec le venv activé : cd notion-mcp-serveur source venv/bin/activate which python # → /Users/votreprenom/notion-mcp-serveur/venv/bin/python # Obtenir le chemin absolu vers serveur.py pwd # → /Users/votreprenom/notion-mcp-serveur # Chemin complet vers serveur.py : # /Users/votreprenom/notion-mcp-serveur/serveur.py

L'icône outils n'apparaît pas ? Vérifiez la Developer Console : View → Developer → Developer Console. Cherchez les erreurs "Failed to start server" qui indiquent généralement un mauvais chemin ou une variable d'environnement manquante.

# Workflow n8n (JSON — importez-le dans votre instance n8n) # Déclencheur : base Notion mise à jour (nouvelle page ajoutée) # Action : Claude lit la page et poste un résumé sur Slack # Étape 1 : Nœud Notion Trigger # - Événement : "Page Added" # - Base : ID de votre base Notes de réunion # Étape 2 : Nœud Anthropic # - Modèle : claude-opus-4-5-20251001 # - Outils : définir en ligne l'outil de lecture de page Notion # - Prompt système : "Tu es un assistant de réunion. Résume les notes # et extrais : date, participants, décisions, points d'action." # - Message utilisateur : "Résume cette page de réunion : {{ $json.id }}" # Étape 3 : Nœud Slack # - Canal : #résumés-réunions # - Message : "{{ $json.message.content[0].text }}" # Définition de l'outil pour lire une page dans le nœud Anthropic : { "name": "lire_page_notion", "description": "Lire le contenu d'une page Notion", "input_schema": { "type": "object", "properties": { "page_id": {"type": "string", "description": "L'identifiant de la page Notion"} }, "required": ["page_id"] } }

# serveur.py — variante transport HTTP # Remplacez la dernière ligne par : if __name__ == "__main__": # stdio local (pour Claude Desktop) : # mcp.run() # HTTP/SSE (pour n8n, accès distant, partage d'équipe) : mcp.run(transport="sse", host="0.0.0.0", port=8000) # Lancer : # python serveur.py # → Serveur MCP démarré sur http://0.0.0.0:8000 # Tester l'endpoint SSE : # curl http://localhost:8000/sse

Workflow : Digest Notion Quotidien ────────────────────────────────────────────────────────────── 1. Schedule Trigger Cron : 0 8 * * 1-5 # 8h du matin en semaine 2. HTTP Request (chercher pages mises à jour) Méthode : POST URL : http://votre-serveur-mcp:8000/call_tool Body : { "tool": "rechercher_notion", "arguments": {"requete": "last modified:yesterday"} } 3. Split in Batches (traiter chaque page) Taille du lot : 1 4. HTTP Request (lire chaque page) Méthode : POST URL : http://votre-serveur-mcp:8000/call_tool Body : { "tool": "lire_page", "arguments": {"page_id": "{{ $json.id }}"} } 5. Nœud Anthropic Modèle : claude-haiku-4-5-20251001 (le plus rapide et économique) Prompt : "Résume en 3 points clés : {{ $json.contenu }}" 6. Nœud Gmail / SMTP À : vous@votreentreprise.com Objet : "Digest Notion Quotidien — {{ $today }}" Corps : Résumés agrégés de l'étape 5 Coût estimé : ~0,002 €/jour (tarification Haiku, moyenne 10 pages)

# Ajouter en haut de serveur.py pour les logs verbeux import logging logging.basicConfig(level=logging.DEBUG) # Ou consulter les logs Claude Desktop : # macOS : ~/Library/Logs/Claude/mcp-server-assistant-notion.log # Windows : %APPDATA%\Claude\Logs\ # Tester le serveur manuellement : NOTION_API_KEY=secret_xxx python serveur.py # → Doit afficher : "Starting MCP server 'Assistant Notion'" # → Si crash immédiat, le message d'erreur indique exactement ce à corriger