MCP pour Débutants : Créer Votre Premier Serveur en 20 Minutes

Qu'est-ce que MCP en Langage Simple ?

MCP (Model Context Protocol) est un protocole ouvert qui permet à Claude (et d'autres IA) d'accéder à des outils et des données que vous définissez. Imaginez que Claude puisse lire vos fichiers, interroger votre base de données, ou envoyer des messages Slack — tout cela de façon sécurisée et contrôlée.

Sans MCP, Claude est limité à son contexte : il ne peut que répondre à partir de ce que vous tapez dans la conversation. Avec MCP, vous lui donnez des "super-pouvoirs" : lire un fichier de configuration, exécuter une requête SQL, chercher dans une documentation technique.

🎯 Ce que vous allez construire dans ce tutoriel

Un serveur MCP qui expose un dossier /workspace à Claude. Claude pourra lister les fichiers, lire leur contenu, et créer de nouveaux fichiers — uniquement dans ce dossier sécurisé. C'est parfait pour générer du code, rédiger de la documentation, ou analyser des fichiers texte.

Comment ça marche : 3 concepts clés

MCP repose sur trois rôles :

Host — l'application qui orchestre tout (ex : Claude Desktop)
Client — le composant dans le Host qui se connecte à un serveur MCP
Server — votre programme qui expose des capacités (lire des fichiers, chercher dans une base, etc.)

La communication se fait via JSON-RPC 2.0 en stdio (processus local) ou HTTP (serveur distant). Le LLM n'appelle jamais directement vos APIs — c'est le serveur MCP qui agit comme intermédiaire sécurisé.

Prérequis

Avant de commencer, assurez-vous d'avoir :

Node.js 18+ installé (node --version doit afficher v18.0.0 ou supérieur)
Un éditeur de code (VS Code, Cursor, ou n'importe quel éditeur)
Claude Desktop installé (télécharger ici)
Notions de base en JavaScript/TypeScript (savoir ce qu'est une fonction, une variable, async/await)

# Vérifier que Node.js est installé
node --version
# → v20.11.0 (ou supérieur)

npm --version
# → 10.2.4 (ou supérieur)

# Si Node n'est pas installé, téléchargez-le depuis https://nodejs.org/

Installation du SDK MCP

Étape 1 : Créer le projet

# Créer un nouveau dossier pour votre serveur MCP
mkdir mcp-filesystem-server
cd mcp-filesystem-server

# Initialiser un projet Node.js
npm init -y

# Installer le SDK MCP officiel d'Anthropic
npm install @modelcontextprotocol/sdk

# Installer les dépendances de développement
npm install --save-dev typescript @types/node tsx

# Vérifier l'installation
npm list @modelcontextprotocol/sdk
# → @modelcontextprotocol/sdk@1.0.4

Étape 2 : Configurer TypeScript

# Créer tsconfig.json
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
EOF

# Créer le dossier source
mkdir src

# Créer le dossier workspace (où Claude pourra lire/écrire)
mkdir workspace

Étape 3 : Ajouter les scripts npm

Ouvrez package.json et ajoutez ces scripts :

{
  "name": "mcp-filesystem-server",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.4"
  },
  "devDependencies": {
    "typescript": "^5.3.3",
    "@types/node": "^20.11.0",
    "tsx": "^4.7.0"
  }
}

Créer le Serveur MCP Filesystem

Créez le fichier src/index.ts avec le code suivant. Chaque section est commentée pour expliquer ce qui se passe.

// src/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import * as fs from "fs/promises";
import * as path from "path";

// Dossier sécurisé où Claude peut lire/écrire
const WORKSPACE_DIR = path.resolve(process.cwd(), "workspace");

// Créer le serveur MCP
const server = new Server(
  {
    name: "filesystem-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// === TOOL 1 : Lister les fichiers du workspace ===
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "list_files",
        description: "Liste tous les fichiers dans le dossier workspace",
        inputSchema: {
          type: "object",
          properties: {},
        },
      },
      {
        name: "read_file",
        description: "Lit le contenu d'un fichier du workspace",
        inputSchema: {
          type: "object",
          properties: {
            filename: {
              type: "string",
              description: "Nom du fichier à lire (ex: notes.txt)",
            },
          },
          required: ["filename"],
        },
      },
      {
        name: "write_file",
        description: "Écrit du contenu dans un fichier du workspace",
        inputSchema: {
          type: "object",
          properties: {
            filename: {
              type: "string",
              description: "Nom du fichier à créer ou écraser",
            },
            content: {
              type: "string",
              description: "Contenu à écrire dans le fichier",
            },
          },
          required: ["filename", "content"],
        },
      },
    ],
  };
});

// === Gérer les appels d'outils ===
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    switch (name) {
      case "list_files": {
        const files = await fs.readdir(WORKSPACE_DIR);
        return {
          content: [
            {
              type: "text",
              text: files.length > 0
                ? `Fichiers dans workspace :
${files.map((f) => `- ${f}`).join("\n")}`
                : "Le dossier workspace est vide.",
            },
          ],
        };
      }

      case "read_file": {
        const filename = args.filename as string;
        const filepath = path.join(WORKSPACE_DIR, filename);

        // Sécurité : empêcher l'accès aux fichiers en dehors du workspace
        if (!filepath.startsWith(WORKSPACE_DIR)) {
          throw new Error("Accès interdit en dehors du workspace");
        }

        const content = await fs.readFile(filepath, "utf-8");
        return {
          content: [
            {
              type: "text",
              text: `Contenu de ${filename} :

${content}`,
            },
          ],
        };
      }

      case "write_file": {
        const filename = args.filename as string;
        const content = args.content as string;
        const filepath = path.join(WORKSPACE_DIR, filename);

        // Sécurité : empêcher l'accès aux fichiers en dehors du workspace
        if (!filepath.startsWith(WORKSPACE_DIR)) {
          throw new Error("Accès interdit en dehors du workspace");
        }

        await fs.writeFile(filepath, content, "utf-8");
        return {
          content: [
            {
              type: "text",
              text: `✅ Fichier ${filename} créé avec succès (${content.length} caractères)`,
            },
          ],
        };
      }

      default:
        throw new Error(`Outil inconnu : ${name}`);
    }
  } catch (error: any) {
    return {
      content: [
        {
          type: "text",
          text: `❌ Erreur : ${error.message}`,
        },
      ],
      isError: true,
    };
  }
});

// === Démarrer le serveur ===
async function main() {
  // S'assurer que le dossier workspace existe
  await fs.mkdir(WORKSPACE_DIR, { recursive: true });

  const transport = new StdioServerTransport();
  await server.connect(transport);

  console.error("Serveur MCP filesystem démarré ✅");
  console.error(`Workspace : ${WORKSPACE_DIR}`);
}

main().catch((error) => {
  console.error("Erreur fatale :", error);
  process.exit(1);
});

Construire le serveur

# Compiler le TypeScript en JavaScript
npm run build

# Vérifier que dist/index.js a été créé
ls dist/
# → index.js

# Tester en mode dev (sans compiler)
npm run dev
# → Serveur MCP filesystem démarré ✅
# → Workspace : /Users/vous/mcp-filesystem-server/workspace

# Ctrl+C pour arrêter

Connecter le Serveur à Claude Desktop

Maintenant que votre serveur MCP est prêt, vous devez le déclarer dans la configuration de Claude Desktop.

Localiser le fichier de configuration

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

Ajouter votre serveur MCP

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/chemin/absolu/vers/mcp-filesystem-server/dist/index.js"
      ]
    }
  }
}

⚠️ Important : Utilisez un chemin ABSOLU

Remplacez /chemin/absolu/vers/mcp-filesystem-server/dist/index.js par le chemin complet sur votre machine. Exemple macOS : /Users/alice/mcp-filesystem-server/dist/index.js

Redémarrer Claude Desktop

macOS : Cmd+Q pour quitter complètement, puis relancer
Windows/Linux : Fermer toutes les fenêtres et relancer

Après redémarrage, ouvrez Claude Desktop. Vous devriez voir une icône d'outil (🔨) en bas de la fenêtre de conversation, indiquant que des serveurs MCP sont connectés.

Tester le Serveur avec de Vraies Conversations

Test 1 : Lister les fichiers

Dans Claude Desktop, tapez :

Vous :

Peux-tu lister les fichiers dans mon workspace ?

Claude devrait automatiquement appeler l'outil list_files et vous répondre :

Claude :

Le dossier workspace est vide.

Test 2 : Créer un fichier

Vous :

Crée un fichier hello.txt qui contient "Bonjour depuis MCP !"

Claude appelle write_file et répond :

Claude :

✅ Fichier hello.txt créé avec succès (20 caractères)

Test 3 : Lire le fichier créé

Vous :

Lis le contenu de hello.txt

Claude :

Contenu de hello.txt :

Bonjour depuis MCP !

Test 4 : Cas d'usage réel — Générer du code

Vous :

Écris un fichier fibonacci.py qui contient une fonction récursive pour calculer le n-ième nombre de Fibonacci, avec des tests unitaires.

Claude va générer le code Python et l'écrire dans workspace/fibonacci.py. Vous pouvez ensuite vérifier le fichier sur votre machine :

# Vérifier que le fichier existe
ls workspace/
# → fibonacci.py  hello.txt

# Lire le contenu
cat workspace/fibonacci.py

# Output attendu :
# def fibonacci(n):
#     if n <= 1:
#         return n
#     return fibonacci(n-1) + fibonacci(n-2)
#
# def test_fibonacci():
#     assert fibonacci(0) == 0
#     assert fibonacci(1) == 1
#     assert fibonacci(10) == 55
#     print("✅ Tous les tests passent")
#
# if __name__ == "__main__":
#     test_fibonacci()

Troubleshooting : Problèmes Courants

Symptôme	Cause	Solution
Le serveur n'apparaît pas dans Claude Desktop	Chemin relatif dans la config ou Claude pas redémarré	Utilisez un chemin absolu. Quittez Claude complètement (Cmd+Q) et relancez
Erreur "Cannot find module"	Le fichier dist/index.js n'existe pas	Lancez `npm run build` pour compiler le TypeScript
Claude dit "I don'have access to that tool"	Le serveur a crashé ou n'est pas démarré	Vérifiez les logs : View → Developer → Developer Console dans Claude Desktop
Erreur "Accès interdit en dehors du workspace"	Tentative de lecture/écriture hors du dossier sécurisé	Normal — c'est la sécurité qui fonctionne. Claude ne peut accéder qu'au dossier workspace
Le serveur démarre puis s'arrête immédiatement	Erreur dans le code ou dépendances manquantes	Lancez `npm run dev` dans un terminal pour voir l'erreur exacte

Déboguer avec les Logs

# Ajouter des logs de debug dans src/index.ts
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  console.error(`[DEBUG] Tool appelé : ${request.params.name}`);
  console.error(`[DEBUG] Args : ${JSON.stringify(request.params.arguments)}`);

  // ... votre code existant
});

# Reconstruire et tester
npm run build

# Les logs apparaîtront dans Developer Console de Claude Desktop
# (View → Developer → Developer Console)

Prochaines Étapes

Félicitations ! Vous avez créé votre premier serveur MCP. Voici comment aller plus loin :

1. Ajouter plus d'outils

Exemples d'outils utiles à ajouter :

search_file — chercher un mot-clé dans tous les fichiers du workspace
delete_file — supprimer un fichier
create_folder — créer des sous-dossiers dans le workspace
run_command — exécuter des commandes shell (attention : risque sécurité !)

2. Connecter une base de données

Créez un serveur MCP qui permet à Claude d'interroger PostgreSQL, MongoDB ou SQLite. Exemple : un outil query_db qui exécute des requêtes SQL et retourne les résultats.

3. Exposer une API externe

Créez un serveur MCP qui appelle des APIs tierces (GitHub, Slack, Notion). Exemple : un outil create_github_issue qui ouvre un ticket sur GitHub directement depuis Claude.

4. Déployer en production

Pour partager votre serveur MCP avec votre équipe, déployez-le sur un serveur distant et configurez le transport HTTP/SSE au lieu de stdio. Consultez la documentation officielle MCP pour les détails.

5. Explorer le registre MCP

Il existe plus de 2 000 serveurs MCP open-source prêts à l'emploi (GitHub, Slack, PostgreSQL, Brave Search, etc.). Consultez le registre officiel MCP pour vous inspirer.

6. Se former en profondeur

Ce tutoriel couvre les bases (Resources, Tools). Pour maîtriser MCP en production (Prompts, Sampling, gestion d'erreurs, sécurité), consultez notre formation Claude API pour Développeurs. Nous couvrons l'API Claude de fond en comble, puis introduisons MCP avec des exercices pratiques de création de serveurs. Formation de 3 jours, finançable OPCO.

Questions Fréquentes

Puis-je créer un serveur MCP sans expérience en TypeScript ?

Oui, avec des bases en JavaScript. Ce tutoriel est conçu pour les débutants et explique chaque ligne de code. Si vous savez ce qu'est une fonction et une variable, vous pouvez suivre. Python est aussi supporté via le SDK officiel, mais TypeScript est recommandé pour débuter (meilleure documentation, plus d'exemples).

Dois-je payer pour utiliser Claude Desktop avec mon serveur MCP ?

Non pour tester en local. Claude Desktop est gratuit pour usage personnel. Vous pouvez utiliser votre serveur MCP avec le plan gratuit de Claude (limité à ~45 messages/jour). Pour usage intensif ou professionnel, Claude Pro (20€/mois) ou API Claude sont nécessaires. Le serveur MCP lui-même ne coûte rien.

Mon serveur MCP peut-il fonctionner avec d'autres outils que Claude Desktop ?

Oui ! MCP est un standard ouvert. Votre serveur fonctionne avec tous les clients MCP : VS Code (extension MCP), Cursor, Windsurf, JetBrains IDEs, Zed, et de nombreux outils no-code. Une fois créé, votre serveur est réutilisable partout.

Que faire si mon serveur MCP ne s'affiche pas dans Claude Desktop ?

Vérifiez 3 choses : (1) Le chemin dans claude_desktop_config.json est absolu, pas relatif. (2) Le fichier index.js existe dans dist/ (lancez `npm run build`). (3) Redémarrez complètement Claude Desktop (Cmd+Q sur Mac, pas juste fermer la fenêtre). Consultez la section Troubleshooting pour plus de diagnostics.

Combien de temps pour maîtriser MCP après ce tutoriel ?

Ce tutoriel : 20-30 minutes pour créer votre premier serveur. Maîtriser MCP au niveau production : 2-3 jours de pratique. Ce guide couvre les fondamentaux (Resources, Tools), mais pas les concepts avancés (Prompts, Sampling, SSE remote servers). Pour aller plus loin, voir notre formation Claude API qui inclut un module MCP complet.

📚 Ressources Complémentaires

Documentation officielle MCP
Registre des serveurs MCP open-source
Formation MCP : Tout Comprendre en 2026 (guide complet)
MCP en Pratique : 5 Serveurs MCP à Déployer Aujourd'hui (tutoriel avancé)

MCP pour Débutants : Créer Votre Premier Serveur en 20 Minutes

Qu'est-ce que MCP en Langage Simple ?

Comment ça marche : 3 concepts clés

Prérequis

Installation du SDK MCP

Étape 1 : Créer le projet

Étape 2 : Configurer TypeScript

Étape 3 : Ajouter les scripts npm

Créer le Serveur MCP Filesystem

Construire le serveur

Connecter le Serveur à Claude Desktop

Localiser le fichier de configuration

Ajouter votre serveur MCP

Redémarrer Claude Desktop

Tester le Serveur avec de Vraies Conversations

Test 1 : Lister les fichiers

Test 2 : Créer un fichier

Test 3 : Lire le fichier créé

Test 4 : Cas d'usage réel — Générer du code

Troubleshooting : Problèmes Courants

Déboguer avec les Logs

Prochaines Étapes

1. Ajouter plus d'outils

2. Connecter une base de données

3. Exposer une API externe

4. Déployer en production

5. Explorer le registre MCP

6. Se former en profondeur

Questions Fréquentes

Puis-je créer un serveur MCP sans expérience en TypeScript ?

Dois-je payer pour utiliser Claude Desktop avec mon serveur MCP ?

Mon serveur MCP peut-il fonctionner avec d'autres outils que Claude Desktop ?

Que faire si mon serveur MCP ne s'affiche pas dans Claude Desktop ?

Combien de temps pour maîtriser MCP après ce tutoriel ?

Maîtrisez MCP et l'API Claude en 3 Jours