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 :

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 !

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

📝 License

MIT License - voir le fichier LICENSE 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.

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 :

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 !

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

📝 License

MIT License - voir le fichier LICENSE 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.