# 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
```bash
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` :
```bash
cp .env.example .env
```
Éditer `.env` avec vos identifiants :
```env
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) :
```json
{
"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 :
```json
{
"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 :
```bash
DB_USER=votre_user DB_PASSWORD=votre_pass node index.js
```
## 📊 Optimisation des tokens
Ce serveur utilise des formats de sortie ultra-compacts :
| Type de données | Format JSON | Format optimisé | Économie |
|----------------|-------------|-----------------|----------|
| Listes simples | `["a","b","c"]` | `a\nb\nc` | ~93% |
| Tables | `[{"col":"val"}]` | `col\|val` | ~75% |
| Structures | JSON indenté | Pipe-separated | ~80% |
**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 [LICENSE](LICENSE) pour plus de détails.
## 🙏 Remerciements
- [Model Context Protocol](https://modelcontextprotocol.io/) par Anthropic
- [mariadb](https://www.npmjs.com/package/mariadb) - Client Node.js pour MariaDB
## 📧 Contact
Pour toute question ou suggestion, ouvrez une [issue](https://github.com/Ophecy/mariadb-mcp-server/issues).
