Ophecy/mariadb-mcp-server

MariaDB MCP Server

🚀 Serveur MCP (Model Context Protocol) optimisé pour interroger une instance MariaDB/MySQL locale avec une consommation minimale de tokens.

✨ Caractéristiques

• 🔍 4 outils MCP : list_databases, list_tables, describe_table, query_database
• 🛡️ Sécurisé : Bloque automatiquement les requêtes destructives (DROP, DELETE, etc.)
• ⚡ Ultra-optimisé : Format de sortie compact (75-95% de tokens économisés vs JSON)
• 🔌 Compatible : Fonctionne avec Warp, Claude Desktop, et tout client MCP
• 📊 Formats lisibles : Sortie en texte brut avec séparateurs \n et |

📦 Installation

Prérequis

• Node.js 18+
• MariaDB ou MySQL installé et accessible
• Un client MCP (Warp, Claude Desktop, etc.)

Étapes

git clone https://github.com/Ophecy/mariadb-mcp-server.git
cd mariadb-mcp-server
npm install

⚙️ Configuration

1. Variables d'environnement

Créer un fichier .env :

cp .env.example .env

Éditer .env avec vos identifiants :

DB_HOST=localhost
DB_PORT=3306
DB_USER=votre_utilisateur
DB_PASSWORD=votre_mot_de_passe
DB_NAME=nom_base_defaut  # optionnel

2. Configuration Warp

Ajouter dans votre configuration Warp (~/.config/warp/mcp_config.json ou équivalent) :

{
  "mcpServers": {
    "mariadb": {
      "command": "node",
      "args": ["/chemin/absolu/vers/mariadb-mcp-server/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "votre_utilisateur",
        "DB_PASSWORD": "votre_mot_de_passe",
        "DB_NAME": "nom_base_defaut"
      }
    }
  }
}

3. Configuration Claude Desktop

Ajouter dans ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou équivalent :

{
  "mcpServers": {
    "mariadb": {
      "command": "node",
      "args": ["/chemin/absolu/vers/mariadb-mcp-server/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "votre_utilisateur",
        "DB_PASSWORD": "votre_mot_de_passe"
      }
    }
  }
}

Redémarrer votre client MCP après la configuration.

🔧 Outils disponibles

list_databases

Liste toutes les bases de données disponibles.

Exemple de sortie :

backend65_test
conversion_queue
converter
dev1

list_tables

Liste toutes les tables d'une base de données.

Paramètres :

• database (optionnel) : Nom de la base

Exemple de sortie :

users
products
orders

describe_table

Affiche la structure complète d'une table.

Paramètres :

• table (requis) : Nom de la table
• database (optionnel) : Nom de la base

Exemple de sortie :

id | int(11) | NO | PRI | - | auto_increment
name | varchar(255) | NO | - | - | -
email | varchar(255) | YES | UNI | - | -

query_database

Exécute une requête SQL SELECT personnalisée.

Paramètres :

• query (requis) : Requête SQL (SELECT, SHOW, DESCRIBE uniquement)

Exemple de sortie :

id | name | email
1 | Alice | alice@example.com
2 | Bob | bob@example.com

🛡️ Sécurité

Protection intégrée : Le serveur bloque automatiquement les requêtes destructives :

• ❌ DROP, DELETE, TRUNCATE
• ❌ ALTER, CREATE
• ❌ INSERT, UPDATE

✅ Seules les requêtes en lecture sont autorisées (SELECT, SHOW, DESCRIBE)

🧪 Test manuel

Pour tester le serveur en ligne de commande :

DB_USER=votre_user DB_PASSWORD=votre_pass node index.js

📊 Optimisation des tokens

Ce serveur utilise des formats de sortie ultra-compacts :

Impact : Réduction drastique des coûts d'API et des temps de réponse ! 🚀

🗺️ Roadmap & Futures évolutions

Version 1.1 (Court terme)

• Support des connexions distantes sécurisées (SSH tunnel)
• Pagination automatique pour les grandes requêtes
• Option --limit pour limiter le nombre de résultats
• Cache des schémas de tables pour réduire les requêtes
• Support des transactions en lecture seule

Version 1.2 (Moyen terme)

• Mode d'écriture optionnel avec confirmation explicite
• Export des résultats (CSV, JSON)
• Statistiques d'utilisation et monitoring
• Support de multiples connexions simultanées
• Interface web pour visualiser les résultats

Version 2.0 (Long terme)

• Support PostgreSQL et SQLite
• Génération automatique de requêtes SQL à partir de langage naturel
• Analyse et suggestions d'optimisation de schéma
• Détection automatique des relations entre tables
• Mode "explain" pour les performances des requêtes
• Snapshots de bases pour comparaisons

Idées à explorer

• Plugin pour VSCode
• Support des vues matérialisées
• Système de permissions granulaire par table
• Audit logs des requêtes exécutées
• Support des procédures stockées (lecture seule)

🤝 Contribution

Les contributions sont les bienvenues !

1. Fork le projet
2. Créer une branche (git checkout -b feature/amelioration)
3. Commit vos changements (git commit -m 'Ajout fonctionnalité')
4. Push vers la branche (git push origin feature/amelioration)
5. Ouvrir une Pull Request

📝 License

MIT License - voir le fichier pour plus de détails.

🙏 Remerciements

• Model Context Protocol par Anthropic
• mariadb - Client Node.js pour MariaDB

📧 Contact

Pour toute question ou suggestion, ouvrez une issue.