Comment déployer GitHub MCP Server : tutoriel multiplateforme Windows, Linux et macOS

GitHub MCP Server est le serveur Model Context Protocol maintenu officiellement par GitHub. Il permet à Cursor, Claude Desktop, VS Code Copilot et autres hôtes IA d'appeler les API REST / GraphQL de GitHub via des outils standardisés — consulter des dépôts, lire des Issues, ouvrir des PR, rechercher du code — sans avoir à coller sans cesse la sortie de commandes gh dans le chat.

Cet article suit l'ordre « d'abord choisir, puis installer l'environnement, enfin connecter l'IDE », couvre les trois chemins d'installation Windows, Linux et macOS, et fournit des extraits de configuration prêts à copier ainsi qu'une liste de dépannage.

Depuis avril 2025, l'ancien paquet npm communautaire @modelcontextprotocol/server-github est obsolète ; le seul miroir local officiellement pris en charge est ghcr.io/github/github-mcp-server, et le point de terminaison hébergé à distance est https://api.githubcopilot.com/mcp/.

Comment choisir le mode de déploiement

Avant d'installer quoi que ce soit, consultez le tableau ci-dessous pour déterminer quelle voie suivre :

Les trois modes partagent la même logique d'authentification : soit configurer un Personal Access Token (PAT), soit utiliser la connexion OAuth via navigateur en mode Docker local / binaire (le token reste en mémoire, jamais écrit sur disque).

Prérequis communs

Quel que soit le chemin choisi, il est recommandé d'effectuer ces quatre étapes au préalable :

1. Créer un PAT GitHub
   Ouvrez la page de création de PAT à granularité fine et cochez les autorisations selon les outils utilisés. Pour une consultation en lecture seule, Contents: Read et Metadata: Read suffisent généralement ; pour créer des PR / Issues, ajoutez les permissions d'écriture.

2. Vérifier la version de l'hôte
   - Cursor : v0.48.0+ requis pour Streamable HTTP à distance
   - Claude Desktop / VS Code : consultez la documentation MCP de chaque outil

3. (Schéma Docker local) Installer et démarrer Docker
   - Windows / macOS : Docker Desktop
   - Linux : Docker Engine + ajouter l'utilisateur courant au groupe docker

4. Pré-tirer l'image (optionnel mais recommandé)

docker pull ghcr.io/github/github-mcp-server

Si le tirage renvoie unauthorized, exécutez docker logout ghcr.io puis réessayez — une session ghcr expirée peut parfois en être la cause.

Mode 1 : hébergé à distance (le plus simple)

GitHub fournit un point de terminaison MCP hébergé sur https://api.githubcopilot.com/mcp/ ; aucun Docker local n'est nécessaire. Convient aux serveurs Linux, aux environnements Windows légers, ou lorsque la politique d'entreprise interdit les conteneurs.

Exemple de configuration Cursor

Modifiez la configuration globale ~/.cursor/mcp.json (sous Windows : %USERPROFILE%\.cursor\mcp.json) :

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    }
  }
}

Remplacez YOUR_GITHUB_PAT par un token réel, enregistrez, puis redémarrez complètement Cursor. Dans Settings → Tools & Integrations → MCP Tools, l'indicateur en ligne devrait être vert ; dans Composer, demandez par exemple « liste mes dépôts GitHub » pour valider.

Points d'attention

• Le mode distant repose principalement sur l'authentification PAT ; la prise en charge OAuth varie encore selon l'hôte.
• Le proxy / pare-feu d'entreprise doit autoriser le trafic HTTPS sortant vers api.githubcopilot.com.
• N'inscrivez pas le PAT dans le dépôt ; si vous utilisez une config au niveau projet dans .cursor/mcp.json, ajoutez-la à .gitignore.

Mode 2 : déploiement Docker local (recommandé officiellement)

Le schéma Docker communique avec l'hôte via stdio : l'hôte lance docker run -i ..., et le processus dans le conteneur lit/écrit sur l'entrée/sortie standard. C'est aussi la commande par défaut derrière les boutons d'installation en un clic de Claude Desktop, Windsurf et Cursor.

Étapes d'installation sur macOS

1. Installez Docker Desktop for Mac (Apple Silicon : version ARM64).
2. L'icône baleine dans la barre de menus doit afficher Running.
3. Vérifiez dans le terminal :

docker run --rm ghcr.io/github/github-mcp-server --help

4. Écrivez dans ~/.cursor/mcp.json :

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

Étapes d'installation sur Linux

1. Installez Docker Engine selon votre distribution (exemple Ubuntu : sudo apt install docker.io).
2. Ajoutez l'utilisateur au groupe docker pour éviter sudo à chaque fois :

sudo usermod -aG docker "$USER"
newgrp docker

3. Assurez-vous que le démon Docker est démarré : sudo systemctl enable --now docker.
4. La configuration MCP est identique à macOS — même chemin ~/.cursor/mcp.json.

Sur un serveur Linux sans interface graphique, si vous ne voulez pas écrire le PAT en clair dans la config, injectez-le via une variable d'environnement :

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"

Puis référencez la même variable dans le bloc env de mcp.json (certains hôtes acceptent la syntaxe ${env:GITHUB_PERSONAL_ACCESS_TOKEN} — voir la doc de l'hôte).

Étapes d'installation sur Windows

1. Installez Docker Desktop for Windows.
   - Backend WSL 2 recommandé (Settings → General → Use WSL 2 based engine).
2. Vérifiez que l'icône Docker Desktop dans la barre des tâches indique un état en cours d'exécution.
3. Chemin de configuration : %USERPROFILE%\.cursor\mcp.json.
4. Le contenu JSON est le même que sur macOS ; command reste docker (Docker Desktop ajoute le CLI au PATH).

Piège fréquent sous Windows : docker fonctionne dans WSL, mais Cursor sous Windows lit mcp.json côté Windows — ne mélangez pas les deux configurations. Si Cursor est installé sous Windows et le projet dans WSL, configurez MCP en priorité dans le répertoire utilisateur Windows.

Connexion OAuth (sans saisir le PAT à la main)

L'image officielle inclut les identifiants d'application OAuth. En mode Docker, mappez le port de rappel vers la boucle locale :

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "127.0.0.1:8085:8085",
        "-e", "GITHUB_OAUTH_CALLBACK_PORT",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_OAUTH_CALLBACK_PORT": "8085"
      }
    }
  }
}

À la première connexion, le navigateur s'ouvre pour la connexion GitHub ; le token reste en mémoire et expire à l'arrêt du conteneur. Sur un serveur sans interface, consultez la procédure de repli device code dans la documentation officielle.

Mode 3 : compilation Go depuis les sources (sans Docker)

Convient lorsque Docker ne peut pas être installé, ou lorsqu'il faut restreindre le toolset (n'exposer qu'une partie des capacités API).

Étapes communes aux trois plateformes

Prérequis : installer Go 1.24+.

git clone https://github.com/github/github-mcp-server.git
cd github-mcp-server
go build -o github-mcp-server cmd/github-mcp-server/main.go

Le nom du binaire compilé est libre ; ci-dessous, ./github-mcp-server sert d'exemple.

Démarrage avec PAT (mode stdio) :

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"
./github-mcp-server stdio

Connexion du binaire local à Cursor :

{
  "mcpServers": {
    "github": {
      "command": "/绝对路径/github-mcp-server",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

Pour mettre à jour : git pull && go build ; pas besoin d'attendre une nouvelle image Docker.

Connexion à d'autres IDE et CLI

Les noms de clés varient selon l'hôte, mais la ligne de commande Docker de base reste la même :

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server

• Claude Desktop : bloc mcpServers dans claude_desktop_config.json, même structure que Cursor.
• VS Code Copilot : distant + local ; en local, l'image Docker est aussi recommandée.
• Claude Code CLI : privilégie un binaire léger pour réduire la charge des conteneurs.

Des exemples complets par hôte se trouvent dans docs/installation-guides/ du dépôt officiel.

Conseils de sécurité et d'exploitation

1. PAT à privilèges minimaux : accordez les permissions selon le toolset, renouvelez régulièrement.
2. Permissions du fichier de config : chmod 600 ~/.cursor/mcp.json (Linux / macOS).
3. Mode lecture seule : des arguments au démarrage peuvent activer read-only pour éviter des modifications accidentelles du dépôt par l'IA.
4. GitHub Enterprise Server en entreprise : OAuth App / GitHub App dédiés requis — les identifiants OAuth par défaut de github.com ne s'appliquent pas ; voir docs/oauth-login.md officiel.

Notes complémentaires selon la plateforme

Chemins et variables d'environnement

~/.cursor/mcp.json

Configuration MCP globale sur macOS et Linux ; sous Windows, équivalent %USERPROFILE%\.cursor\mcp.json.

GITHUB_PERSONAL_ACCESS_TOKEN

Nom de la variable d'environnement PAT en mode Docker / binaire ; une fois définie, elle prime sur le flux OAuth.

GITHUB_OAUTH_CALLBACK_PORT

Port d'écoute du rappel OAuth navigateur ; en Docker, souvent fixé à 8085.

Raccourcis et habitudes

Dans Cursor Composer, Cmd+Shift+P (sous Windows : Ctrl+Shift+P) ouvre la palette de commandes pour rechercher les réglages MCP. Autrefois, certains lançaient le service en une ligne avec npx @modelcontextprotocol/server-github — cette méthode est obsolète ; utilisez plutôt Docker ou le point de terminaison distant décrits ici.

En production, placez le PAT dans une variable d'environnement ou un gestionnaire de secrets, pas dans un fichier de projet suivi par git.

Liste de vérification (avant mise en production)

1. Point vert dans le panneau MCP
2. La liste d'outils affiche des entrées préfixées github_*
3. Un appel en lecture seule (ex. lister les dépôts) réussit

Où consulter les journaux

Les logs Cursor : Help → Toggle Developer Tools → Console, filtrez sur le mot-clé MCP ; le chemin des logs Claude Desktop varie selon la plateforme — la section troubleshooting officielle liste tout.

Dépannage rapide

Auto-contrôle rapide : lancez la commande Docker manuellement en terminal et regardez si stderr signale une erreur immédiate ; comparez avec la commande de démarrage MCP dans les logs de l'IDE.

En résumé

• Pour démarrer le plus vite : distant https://api.githubcopilot.com/mcp/ + PAT, Cursor v0.48+ avec url.
• Pour une installation stable et reproductible : sur les trois plateformes, docker run -i --rm ... ghcr.io/github/github-mcp-server.
• Pour un déploiement léger ou sur mesure : go build du binaire, connexion en stdio.

Une fois déployé, l'intérêt de MCP apparaît dans le dialogue avec l'IA — par exemple « résume les 5 dernières open issues du dépôt kvmkit ». Si vous montez en parallèle une pipeline CI/CD ou des nœuds de build Mac cloud 7×24, vous pouvez aligner l'assistance MCP au développement et la publication automatisée dans la même chaîne d'outils.

FAQ