Keep/docs/guide-utilisateur-mcp.md

Guide Utilisateur : MCP dans Keep Notes

Table des matières

1. Qu'est-ce que MCP ? (en termes simples)
2. Comment ça marche dans Keep Notes
3. Les clés API : à quoi ça sert
4. Gérer ses clés API depuis l'interface
5. Configurer Claude Code
6. Configurer Cursor
7. Configurer N8N
8. Questions fréquentes

---

1. Qu'est-ce que MCP ? (en termes simples)

MCP = Model Context Protocol (Protocole de Contexte de Modèle).

C'est un standard qui permet à des outils IA (comme Claude, Cursor, N8N) de parler à votre application Keep Notes.

Analogie simple

Imaginez que Keep Notes est un restaurant. Normalement, pour lire le menu ou commander, vous devez ouvrir l'application web dans votre navigateur.

MCP, c'est comme un service de livraison : il permet à d'autres applications de passer des commandes directement au restaurant, sans ouvrir le site web. Votre clé API, c'est votre numéro de client qui prouve que vous avez le droit de commander.

Concrètement, que permet MCP ?

Avec MCP, vous pouvez depuis Claude Code, Cursor ou N8N :

• Lire vos notes existantes
• Créer de nouvelles notes
• Rechercher dans vos notes (recherche sémantique IA)
• Organiser vos notes dans des carnets
• Gérer vos étiquettes
• Générer des titres avec l'IA
• Et 30+ autres actions

Les deux modes de connexion

Votre serveur MCP Keep Notes peut fonctionner de deux façons :

Mode	Comment ça marche	Pour qui	Clé API nécessaire ?
Stdio	L'outil IA lance directement le serveur MCP en arrière-plan	Claude Code, Cursor (local)	Non
HTTP	Le serveur MCP tourne en continu sur le port 3001, les outils s'y connectent via le réseau	N8N, Cursor (distant), tout outil réseau	Oui

---

2. Comment ça marche dans Keep Notes

Votre projet Keep Notes contient deux serveurs qui partagent la même base de données :

Keep/
├── keep-notes/          ← Application web (port 3000)
│   └── prisma/dev.db    ← Base de données SQLite
│
└── mcp-server/          ← Serveur MCP (port 3001 en mode HTTP)
    ├── index.js         ← Mode Stdio
    ├── index-sse.js     ← Mode HTTP
    └── tools.js         ← Les 37 outils disponibles

Important : Les deux serveurs accèdent à la même base de données. Quand vous créez une note via MCP, elle apparaît immédiatement dans l'interface web, et inversement.

---

3. Les clés API : à quoi ça sert

Une clé API est un mot de passe secret qui permet à un outil externe de prouver son identité au serveur MCP.

Quand vous avez besoin d'une clé API

• Mode HTTP (N8N, Cursor distant, etc.) : OUI, vous devez fournir votre clé API à chaque requête.
• Mode Stdio (Claude Code, Cursor local) : NON, l'outil accède directement à la base de données.

Format d'une clé

Les clés générées par Keep Notes ressemblent à ça :

mcp_sk_0f0fe746d34dabdf7370d06352a2fd5fabf5994d2a980a31

• Préfixe mcp_sk_ (pour "MCP Secret Key")
• Suivi de 48 caractères hexadécimaux

Securité

• La clé brute n'est affichée qu'une seule fois au moment de sa création
• En base de données, seul le hash SHA-256 est stocké (comme un mot de passe)
• Personne (même pas vous) ne peut retrouver la clé brute après fermeture de la fenêtre
• Si vous perdez une clé, il faut la révoquer et en générer une nouvelle

---

4. Gérer ses clés API depuis l'interface

Accéder à la page MCP

1. Ouvrez Keep Notes dans votre navigateur (http://localhost:3000)
2. Cliquez sur Paramètres (icône engrenage)
3. Dans le menu latéral, cliquez sur MCP Settings (icône clé)

Générer une nouvelle clé

1. Cliquez sur le bouton "Générer une nouvelle clé"
2. Donnez un nom à votre clé (ex: "Mon Claude Code", "N8N Prod")
3. Cliquez sur "Générer"
4. Copiez immédiatement la clé — elle ne sera plus jamais visible
5. Cliquez sur "Terminé"

Gérer vos clés existantes

Pour chaque clé, vous verrez :

• Le nom que vous lui avez donné
• La date de création
• La date de dernière utilisation
• Le statut : Active (verte) ou Révoquée (grise)

Révoquer une clé

La révocation désactive la clé sans la supprimer. L'outil qui l'utilisait perdra son accès.

Utile si vous pensez qu'une clé a été compromise mais voulez garder un historique.

Supprimer une clé

La suppression est définitive. La clé et son historique disparaissent.

---

5. Configurer Claude Code

Claude Code est l'outil en ligne de commande de Claude (celui que vous utilisez actuellement).

Méthode recommandée : Mode Stdio (sans clé API)

Avec le mode stdio, Claude Code lance le serveur MCP directement. Pas besoin de clé API car il accède à la base SQLite directement.

Étape 1 : Ouvrir la configuration MCP

Dans votre terminal Claude Code, tapez :

/mcp

Étape 2 : Ajouter le serveur

Choisissez d'ajouter un nouveau serveur et collez cette configuration :

{
  "mcpServers": {
    "keep-notes": {
      "command": "node",
      "args": ["/Users/sepehr/dev/Keep/mcp-server/index.js"],
      "env": {
        "DATABASE_URL": "file:/Users/sepehr/dev/Keep/keep-notes/prisma/dev.db",
        "APP_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

Explication de chaque champ

Champ	Valeur	À quoi ça sert
command	"node"	Lance Node.js
args	["/chemin/vers/mcp-server/index.js"]	Chemin vers le serveur MCP (mode stdio)
env.DATABASE_URL	"file:/chemin/vers/prisma/dev.db"	Où trouver la base de données
env.APP_BASE_URL	"http://localhost:3000"	URL de l'app web (pour les fonctions IA)

Étape 3 : Vérifier

Redémarrez Claude Code. Tapez un message demandant d'utiliser un outil Keep Notes, par exemple :

"Liste mes notes Keep Notes"

Claude Code devrait automatiquement détecter les outils MCP disponibles.

Méthode alternative : fichier de configuration

Vous pouvez aussi éditer directement le fichier de config :

# Configuration globale (tous les projets)
nano ~/.claude.json

# OU configuration par projet
nano /Users/sepehr/dev/Keep/.claude/settings.local.json

Ajoutez le bloc mcpServers dans le fichier JSON.

---

6. Configurer Cursor

Cursor est un éditeur de code avec IA intégrée qui supporte MCP.

Mode local (Stdio — sans clé API)

Ouvrez les paramètres MCP dans Cursor (Settings > MCP) et ajoutez :

{
  "mcpServers": {
    "keep-notes": {
      "command": "node",
      "args": ["/Users/sepehr/dev/Keep/mcp-server/index.js"],
      "env": {
        "DATABASE_URL": "file:/Users/sepehr/dev/Keep/keep-notes/prisma/dev.db",
        "APP_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

C'est exactement la même config que Claude Code en mode stdio.

Mode distant (HTTP — avec clé API)

Si le serveur MCP tourne sur une autre machine ou si vous préférez le mode HTTP :

1. Démarrez le serveur MCP en mode HTTP

cd /Users/sepehr/dev/Keep/mcp-server
node index-sse.js

Le serveur démarre sur http://localhost:3001.

2. Configurez Cursor

{
  "mcpServers": {
    "keep-notes": {
      "url": "http://localhost:3001/mcp",
      "headers": {
        "x-api-key": "mcp_sk_VOTRE_CLE_API_ICI"
      }
    }
  }
}

Remplacez mcp_sk_VOTRE_CLE_API_ICI par votre vraie clé (générée depuis /settings/mcp).

---

7. Configurer N8N

N8N est un outil d'automatisation qui peut utiliser MCP pour interagir avec vos notes.

Prérequis

1. Le serveur MCP doit tourner en mode HTTP :

cd /Users/sepehr/dev/Keep/mcp-server
node index-sse.js

2. Vous devez avoir généré une clé API depuis /settings/mcp

Configuration dans N8N

Étape 1 : Ajouter un nœud MCP Client

Dans votre workflow N8N, ajoutez un nœud "MCP Client".

Étape 2 : Configurer la connexion

Paramètre	Valeur
Transport	HTTP Streamable
URL	http://VOTRE_IP:3001/mcp
Authentication	API Key
Header	x-api-key
Valeur	mcp_sk_VOTRE_CLE_API_ICI

Trouver votre IP locale

# macOS
ifconfig | grep "inet " | grep -v 127.0.0.1

# Résultat typique : 192.168.1.XX

Utilisez cette IP (pas localhost) si N8N tourne sur une autre machine.

Étape 3 : Utiliser un outil

Après connexion, N8N charge la liste des 37 outils disponibles. Choisissez celui que vous voulez utiliser, par exemple :

• create_note — Créer une note
• search_notes — Rechercher des notes
• get_notes — Lister les notes

Exemple de workflow

Workflow "Sauvegarder un article web en note" :

Webhook (reçoit un article)
    → MCP Client : create_note
        title = article.title
        content = article.body
        labels = ["article", "web"]

---

8. Questions fréquentes

J'ai perdu ma clé API, que faire ?

Les clés ne sont jamais stockées en clair. Si vous avez perdu une clé :

1. Allez dans /settings/mcp
2. Révoquez l'ancienne clé
3. Générez une nouvelle clé
4. Copiez-la immédiatement
5. Mettez à jour la config de votre outil (Claude Code, Cursor, N8N)

Peut-on utiliser MCP sans clé API ?

Oui, en mode stdio. C'est le cas pour Claude Code et Cursor configurés en local. La clé API n'est nécessaire que pour le mode HTTP distant.

Le serveur MCP doit-il tourner en permanence ?

• Mode Stdio : Non. L'outil (Claude Code/Cursor) lance le serveur automatiquement quand il en a besoin.
• Mode HTTP : Oui. Le serveur doit tourner en continu (node index-sse.js) pour que N8N et les autres outils puissent s'y connecter.

Mes notes sont-elles en sécurité ?

• Les clés API sont hashées (SHA-256) en base de données, comme des mots de passe
• Le serveur MCP accède à la même base que l'app web — les permissions utilisateur sont respectées
• En mode HTTP, le trafic peut être sécurisé avec HTTPS (configuration du reverse proxy)

Combien de clés API puis-je créer ?

Pas de limite. Il est recommandé de créer une clé par outil (une pour Claude Code, une pour N8N, etc.) pour pouvoir les révoquer indépendamment.

Quels sont les 37 outils disponibles ?

Catégorie	Outils
Notes	create_note, get_note, get_notes, update_note, delete_note, search_notes, toggle_pin, toggle_archive, export_notes, import_notes, restore_note
Carnets	create_notebook, get_notebooks, get_notebook, update_notebook, delete_notebook, reorder_notebooks
Etiquettes	create_label, get_labels, update_label, delete_label
IA	generate_title_suggestions, reformulate_text, generate_tags, fuse_notes, batch_organize, generate_notebook_summary, etc.
Rappels	get_due_reminders
Clés API	generate_api_key, list_api_keys, revoke_api_key