mcp-cowork

Serveur MCP (Model Context Protocol) exposé en HTTP distant, protégé par OAuth, conçu pour être ajouté comme connecteur dans Claude Desktop ou Claude.ai ("Cowork"). Il expose une large boîte à outils d'intégrations (GitHub, Microsoft 365, Google, OVH, o2switch, Steam, WhatsApp, transport, école, NAS Synology, notifications Pushover/ntfy).

Sommaire des tools

Les tools WhatsApp appellent un daemon externe séparé (whatsapp-daemon sur le déploiement de référence, tournant sous pm2 sur la même machine) — ce repo ne le démarre pas, il s'y connecte seulement via modules/whatsapp.js.

Related MCP server: MCP OAuth Sample

Architecture

• Express + Streamable HTTP (@modelcontextprotocol/sdk) : chaque session MCP obtient sa propre instance McpServer (createServer() dans index.js). Un McpServer ne peut être connecté qu'à un seul transport à la fois — réenregistrer les mêmes tools à chaque session est stateless et sans coût réel.

• OAuth : mcpAuthRouter du SDK monte /register, /authorize, /token, /revoke et les endpoints .well-known. Seul, ce router approuve automatiquement toute demande d'autorisation (voir modules/oauth.js, provider.authorize()).

• Contrôle d'accès réel : modules/authGate.js intercepte /authorize avant le router OAuth et exige une passphrase (MCP_GATE_PASSPHRASE), avec verrouillage après 5 tentatives échouées / 15 min. C'est cette couche, pas l'OAuth du SDK, qui protège effectivement le serveur.

⚠️ État en mémoire (important après un restart)

Le provider OAuth (modules/oauth.js) reste entièrement en mémoire — un redémarrage du process invalide tous les tokens OAuth émis, et chaque client déjà connecté (Claude Desktop/Claude.ai) devra refaire l'authentification OAuth après un restart ou une bascule. C'est un effet de bord attendu, pas un bug.

Les sessions authGate (issues d'une passphrase validée), elles, sont persistées dans data/gate_sessions.json (même mécanisme que data/google_token.json pour Google) : un redémarrage du process ne redemande donc plus la passphrase tant que le cookie francis_gate (30 jours) est encore valide.

Installation

git clone <repo> mcp-cowork
cd mcp-cowork
npm install
cp .env.example .env
# éditer .env avec les vraies valeurs
pm2 start ecosystem.config.js

Configuration (variables d'environnement)

Toutes les intégrations sont optionnelles — sans leurs variables, les tools correspondants renvoient une erreur explicite au lieu de planter le serveur.

Exploitation (pm2)

pm2 status
pm2 logs mcp-cowork
pm2 restart mcp-cowork
pm2 save   # à faire après tout changement pour persister au reboot

Changer MCP_PUBLIC_URL (ex : nouvelle URL de tunnel) impose un pm2 restart et de reconfigurer le connecteur côté client (nouvel issuer OAuth).

Page de statut

Une page de diagnostic web est disponible à l'adresse /status (protégée par la même passphrase que /authorize). Elle affiche en temps réel :

• Serveur : version, uptime, heure de démarrage, port, URL publique

• Sessions MCP : nombre de sessions Streamable HTTP actives (clients connectés via Claude Desktop/Claude.ai)

• OAuth : nombre de clients enregistrés, d'access tokens et de refresh tokens en mémoire (rappel : état perdu au restart)

• authGate : nombre de sessions passphrase validées persistées sur disque

• Modules & Outils : liste des 14 modules avec statut configuré/non-configuré selon les variables d'environnement présentes

La page est en lecture seule — aucune action déclenchable. Accès : https://[MCP_PUBLIC_URL]/status avec la même passphrase que la protection OAuth.

Dépendances externes

• Un daemon whatsapp-daemon séparé (pm2, même machine) pour les tools WhatsApp.

• Python + pronotepy installés si les tools Pronote sont utilisés (scripts/pronote.py).

• Un tunnel HTTPS public (ex. ngrok) pointant vers MCP_HTTP_PORT, pour l'exposition en tant que connecteur distant.

docs/manifest.json

Manifeste au format Desktop Extension (.mcpb), non utilisé au runtime dans ce mode de déploiement (connecteur distant + pm2). Conservé en référence pour un éventuel packaging futur en extension installable localement dans Claude Desktop.