iopool-mcp

Serveur MCP (Model Context Protocol) distant pour consulter les données de votre piscine iopool (température, pH, ORP, mode, recommandation de filtration) directement depuis un assistant compatible MCP (Claude, etc.).

Pourquoi

L'API publique iopool (documentation) n'a pas de connecteur MCP officiel. Ce projet en propose un, hébergé, sans avoir besoin de faire tourner quoi que ce soit en local.

Related MCP server: WHOOP MCP Server

Outils exposés

Récupérer sa clé API iopool

Dans l'application mobile iopool : Plus > Réglages > Clé API.

Configuration du connecteur MCP

Deux méthodes d'authentification. Choisissez selon votre client.

Méthode A — OAuth (claude.ai, web et mobile)

Le formulaire « Ajouter un connecteur personnalisé » de claude.ai ne propose ni champ d'en-tête ni jeton statique : OAuth est la seule option. Ce serveur embarque donc son propre serveur d'autorisation.

Dans Réglages > Connecteurs > Ajouter un connecteur personnalisé :

Laissez les champs client vides : le serveur accepte l'enregistrement dynamique (RFC 7591). À la connexion, une page s'ouvre et vous demande votre clé API iopool ; elle est vérifiée auprès d'iopool, puis chiffrée à l'intérieur du jeton remis à Claude. Vous ne la ressaisissez plus ensuite.

Méthode B — clé directe (Claude Code, Claude Desktop, curl)

• URL : https://iopool-mcp.vercel.app/api/mcp

• En-tête : Authorization: Bearer <votre_cle_api_iopool>

• Repli accepté : x-iopool-api-key: <votre_cle_api_iopool>

Claude Code :

claude mcp add --transport http iopool https://iopool-mcp.vercel.app/api/mcp \
  --header "Authorization: Bearer VOTRE_CLE_API_IOPOOL"

Claude Desktop (claude_desktop_config.json) :

{
  "mcpServers": {
    "iopool": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://iopool-mcp.vercel.app/api/mcp",
        "--header", "Authorization:Bearer VOTRE_CLE_API_IOPOOL"
      ]
    }
  }
}

Vérifier en ligne de commande

curl -s https://iopool-mcp.vercel.app/api/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $IOPOOL_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_pools","arguments":{}}}'

Une requête sans en-tête Authorization reçoit un 401 accompagné de WWW-Authenticate, ce qui déclenche le parcours OAuth côté client.

Déployer votre propre instance

Ce dépôt est réutilisable tel quel. Connectez-le à un projet Vercel, puis :

1. Ajoutez une variable d'environnement TOKEN_SECRET (32 caractères minimum, aléatoire). Elle sert à chiffrer les jetons OAuth. Générez-la avec openssl rand -base64 32.

2. Désactivez Vercel Authentication dans Settings > Deployment Protection, sinon les clients MCP se heurtent à un écran de connexion.

Sans TOKEN_SECRET, les endpoints OAuth renvoient une erreur explicite et seule l'authentification par en-tête fonctionne.

Pour vérifier que la variable est bien prise en compte, appelez la racine : GET / renvoie "oauth": "configured" une fois qu'elle est en place. Une variable ajoutée après le dernier déploiement n'est pas visible tant que le projet n'a pas été redéployé.

Endpoints OAuth exposés

PKCE S256 est obligatoire, et les redirect_uri sont restreints aux domaines claude.ai et aux boucles locales.

Confidentialité

Aucune clé n'est stockée côté serveur : il n'y a ni base de données, ni session, ni journalisation de clé.

En authentification directe, la clé est lue dans l'en-tête et transmise à l'API iopool le temps de l'appel. En OAuth, elle est chiffrée en AES-256-GCM à l'intérieur du jeton remis au client : le serveur la déchiffre à chaque requête, s'en sert, et l'oublie. Un jeton volé est inutilisable sans TOKEN_SECRET, et changer cette variable révoque tous les jetons émis.

Chaque utilisateur utilise donc sa propre clé : un déploiement partagé ne donne accès à aucune piscine tant que l'appelant ne fournit pas la sienne.

Déploiement

Fonctions serverless Node.js sur Vercel, zéro dépendance (fetch et crypto natifs, Node >= 18). Chaque push sur la branche de production redéploie automatiquement.

Les routes OAuth sont listées plus haut.

Licence

MIT