mysql_mcp_server : exposer MySQL à un agent sans lui donner les clés du serveur

Le problème : un agent qui doit lire une base sans la modifier

Un agent conversationnel qui a besoin de connaître un schéma de base de données se retrouve face à deux mauvaises options. La première consiste à coller le résultat d'un mysqldump ou d'un SHOW CREATE TABLE dans le contexte de la conversation : volumineux, figé, et obsolète dès la première migration. La seconde consiste à donner à l'agent un accès direct au client MySQL en ligne de commande, ce qui revient à lui donner aussi la possibilité d'exécuter un DROP TABLE.

mysql_mcp_server se place entre les deux. Il implémente le Model Context Protocol, un protocole qui permet à une application hôte (Claude Code, Claude Desktop, ou tout autre client MCP) de découvrir et d'appeler des outils exposés par un processus séparé. Le serveur se connecte à MySQL, et le client ne voit que les outils déclarés : lister les tables, lire un schéma, échantillonner des lignes, exécuter une requête SQL. La base n'est jamais exposée directement, elle est médiée.

Le public visé est précis : un ingénieur qui utilise déjà un client MCP et qui veut lui donner une vue sur une base MySQL de développement, de recette, ou de production en lecture. Ce n'est pas un outil d'administration de base de données, et ce n'est pas non plus une passerelle SQL générique pour applications.

Quatre outils, un seul chemin d'exécution

Le README documente trois outils et un quatrième implicite. execute_sql prend une chaîne query et accepte SELECT, SHOW, DESCRIBE, ainsi que les instructions DML (INSERT, UPDATE, DELETE). Ces dernières sont signalées au client par un indicateur destructif, ce qui permet à l'hôte de demander confirmation avant exécution. get_schema_info renvoie les noms de colonnes, les types, la nullabilité, les valeurs par défaut et les commentaires, avec un argument table_name optionnel. get_table_sample renvoie un échantillon de lignes, avec une limite plafonnée à 20. Enfin, list_resources expose les tables comme ressources MCP.

La contrainte structurelle est la même pour tous : une seule instruction par appel. Le README le répète à deux endroits, dans la section sur le mode multi-base et dans la description de execute_sql. Une séquence du type USE db; SELECT ... ne passe pas. Il faut donc écrire des requêtes pleinement qualifiées, et c'est cohérent avec le mode multi-base décrit plus bas.

Deuxième contrainte, moins visible : les identifiants passés à get_schema_info et get_table_sample sont filtrés. Le README précise qu'ils ne peuvent contenir que des caractères alphanumériques, des underscores et le signe dollar, le point étant autorisé comme séparateur entre base et table. C'est une validation d'identifiant, pas une validation de requête. Pour execute_sql, rien de tel n'est documenté : la chaîne query part telle quelle vers le connecteur. La surface d'injection dépend donc du compte MySQL utilisé, pas d'un analyseur syntaxique côté serveur.

Configuration : des variables d'environnement, et un piège de répertoire courant

L'installation manuelle tient en une commande : pip install mysql-mcp-server. L'enregistrement auprès de Claude Code se fait avec claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server. Pour Autohand Code CLI, la commande documentée est autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server, avec une option --scope project pour garder l'enregistrement dans l'espace de travail courant.

Les variables obligatoires sont MYSQL_HOST, MYSQL_USER et MYSQL_PASSWORD. MYSQL_PORT vaut 3306 par défaut, MYSQL_DATABASE est optionnel et son absence déclenche le mode multi-base. Les variables avancées couvrent MYSQL_SSL_MODE (DISABLED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY), MYSQL_CONNECT_TIMEOUT, MYSQL_SQL_MODE avec TRADITIONAL comme valeur par défaut, MYSQL_CHARSET, MYSQL_COLLATION, MYSQL_AUTH_PLUGIN pour les anciennes versions de MySQL, MYSQL_USE_PURE pour forcer le connecteur en Python pur, et MYSQL_RAISE_ON_WARNINGS.

Le détail qui provoquera le plus d'heures perdues est le chargement du fichier .env. Le serveur le lit via python-dotenv depuis le répertoire de travail du processus, et remonte dans les répertoires parents. Le README signale explicitement que Claude Code et Claude Desktop lancent le serveur depuis leur propre répertoire de travail : le .env du projet ne sera pas trouvé et l'erreur affichée sera Missing required database configuration. La solution documentée est de placer les valeurs MYSQL_* dans le bloc env de la configuration MCP, pas dans un fichier. C'est un piège de conception, pas un bug, mais il faut le connaître avant de déboguer une connexion qui semble correcte en ligne de commande.

Mode multi-base et tunnel SSH : deux réponses à des contraintes réseau

Quand MYSQL_DATABASE n'est pas défini, list_resources renvoie toutes les bases utilisateur, les bases système étant filtrées. Les requêtes doivent alors utiliser la notation database.table. Les deux outils d'inspection acceptent aussi cette notation, un nom nu se résolvant vers la base configurée. C'est pratique pour un agent qui doit comparer deux schémas, mais cela élargit mécaniquement la surface visible : l'agent voit toutes les bases que le compte peut atteindre, pas seulement celle que vous aviez en tête.

Le tunnel SSH répond à un autre problème, celui d'une base non exposée sur le réseau. Les variables MYSQL_SSH_ENABLE, MYSQL_SSH_HOST, MYSQL_SSH_PORT, MYSQL_SSH_USER, MYSQL_SSH_KEY_PATH, MYSQL_SSH_REMOTE_HOST, MYSQL_SSH_REMOTE_PORT et MYSQL_LOCAL_PORT décrivent un rebond par un hôte intermédiaire, avec MYSQL_LOCAL_PORT qui vaut 3330 dans l'exemple. Le README ne détaille pas la bibliothèque utilisée pour ce tunnel ni son comportement en cas de coupure. Si votre environnement impose un bastion avec authentification à deux facteurs ou un agent SSH, cette partie est à vérifier dans le code avant de compter dessus.

Le transport SSE mérite la même prudence. MCP_TRANSPORT=sse active un serveur HTTP, avec MCP_SSE_HOST, PORT ou MCP_SSE_PORT, et MCP_SSE_ALLOWED_HOSTS. La valeur par défaut de MCP_SSE_ALLOWED_HOSTS est localhost:{port},127.0.0.1:{port}, et le README note que MCP_SSE_HOST=0.0.0.0 est requis pour Docker ou l'hébergement. Autrement dit, la configuration par défaut protège contre la requête DNS rebinding, mais l'ouvrir sur toutes les interfaces sans ajuster la liste des hôtes autorisés revient à exposer un exécuteur SQL. Le README recommande le mode SSE pour les déploiements distants ou auto-hébergés, ce qui rend ce réglage d'autant plus important.

Ce que le serveur ne protège pas

La limitation centrale n'est pas dans le code, elle est dans le modèle de sécurité annoncé. Le README parle d'un accès sécurisé via des variables d'environnement. C'est exact au sens où les identifiants ne sont pas dans le contexte de la conversation. Mais il n'existe aucune couche d'autorisation interne documentée : pas de liste blanche de tables, pas de blocage des instructions DML, pas de mode lecture seule. execute_sql accepte INSERT, UPDATE et DELETE, marqués comme destructifs pour que le client demande confirmation. Cette confirmation est une décision de l'hôte, pas du serveur.

La conséquence pratique est simple : le périmètre réel de l'agent est exactement celui du compte MySQL configuré. Si vous mettez un compte root dans MYSQL_USER, l'agent peut tout faire. La seule barrière solide est donc côté MySQL, avec un utilisateur limité à SELECT sur les schémas concernés. Le README ne fournit pas d'exemple de création de ce compte, et c'est un manque.

Deuxième cas où l'outil est mal choisi : l'analyse de gros volumes. get_table_sample plafonne à 20 lignes, ce qui est un choix raisonnable pour éviter de saturer le contexte, mais insuffisant pour du profilage statistique. Et execute_sql ne renvoie qu'une instruction à la fois, sans pagination documentée. Pour explorer une table de plusieurs millions de lignes, un client SQL classique reste plus adapté. Enfin, l'absence de support multi-instructions interdit les scripts de migration ou de nettoyage en plusieurs étapes, ce qui n'est pas un défaut pour l'usage visé mais élimine certaines utilisations détournées.

Face à quoi on le compare réellement

L'alternative évidente n'est pas un autre serveur MCP, c'est le client MySQL en ligne de commande, ou un client graphique, utilisé par un humain. La différence d'approche est nette. Avec mysql en terminal, vous tapez la requête, vous lisez le résultat, vous décidez. Avec mysql_mcp_server, c'est le modèle de langage qui formule la requête à partir d'une question en langage naturel, et qui interprète le résultat. Le serveur ne fait que transporter. Cela signifie que la qualité de l'exploration dépend du modèle, pas de l'outil, et que le coût en jetons du schéma renvoyé devient un facteur concret dès que la base compte beaucoup de tables.

Un ORM comme SQLAlchemy avec un agent qui génère du Python résoudrait un problème différent : il donnerait accès aux données via du code exécuté, avec les garde-fous du langage. mysql_mcp_server choisit l'inverse, une interface étroite et déclarative, au prix d'une expressivité limitée à une instruction SQL par appel. Ce compromis est cohérent avec MCP, qui est conçu pour des appels d'outils courts et vérifiables.

Sur la maintenance, les éléments disponibles indiquent un rythme de publication soutenu : v0.4.2 en juin 2026, puis v0.4.3 et v0.4.4 les 30 et 31 juillet 2026, le dépôt ayant reçu une poussée le 2 août 2026. Le projet n'est pas archivé. La version 0.4.x signale une API encore en mouvement, ce qui implique de relire les notes de version avant de mettre à jour un déploiement en production. La licence MIT est permissive : redistribution et usage commercial autorisés, avec conservation du texte de licence. Elle n'offre aucune garantie, ce qui est la contrepartie habituelle, et rien dans le dépôt ne suggère un support commercial. À noter que le README mentionne un hébergement tiers et une installation via Smithery, deux services distincts du code sous licence MIT, dont les conditions vous concernent séparément.

Conclusion éditoriale

Adoptez mysql_mcp_server si vous voulez qu'un client MCP explore un schéma MySQL en lecture, avec un compte dédié et des privilèges restreints côté serveur MySQL. Ne l'adoptez pas si vous attendez une couche d'autorisation interne : elle n'existe pas, le serveur transmet ce que le compte MySQL autorise. Avant tout déploiement, vérifiez trois choses concrètes : le comportement réel du compte face à une requête DML, la présence de vos identifiants dans le bloc env de la configuration MCP plutôt que dans un fichier .env, et la valeur de MCP_SSE_ALLOWED_HOSTS si vous passez en mode SSE.

Sources officielles

1. designcomputer/mysql_mcp_server on GitHub
2. License: MIT
3. Project website
4. README
5. Releases