convez.ai
MCP ServerIntegração & APIsIntermediário
neodelphis

MCP Server DB SQLite

neodelphis/mcp-server-db

Acesso seguro a SQLite via MCP com Docker

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que permite a IAs como Claude e Gemini consultarem bancos de dados SQLite em linguagem natural, encapsulado em Docker com suporte a leitura segura. Expõe ferramentas para descobrir esquemas e executar queries.

Instalação

$npx convez-ai neodelphis/mcp-server-db

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
14%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Permitir que agentes IA consultem dados em linguagem natural
  • Construir assistentes técnicos com acesso ao contexto de banco de dados
  • Disponibilizar schemas e queries para exploração de dados sem risco de escrita

Veredito

Implementação pedagógica sólida de servidor MCP com Docker. Oferece isolamento seguro (read-only) e estrutura clara para quem quer integrar IAs com bancos de dados SQLite, embora seja mais um exemplo educacional que solução pronta para produção.

README

A tradução para o português deste README ainda está na fila.

MCP SQLite Server - Guide de Mise en Place

Ce projet est un exemple pédagogique de serveur Model Context Protocol (MCP) encapsulé dans Docker. Il permet à une IA (comme Gemini ou Claude) d'interagir avec une base de données SQLite en langage naturel.

1. Structure du Projet

.
├── data/               # Dossier hôte pour la persistance de la DB
├── Dockerfile          # Définition de l'image Docker
├── docker-compose.yml  # Orchestration et configuration simplifiée
├── init_db.py          # Script d'initialisation des données
└── mcp_server_db.py    # Code principal du serveur MCP

2. Étape par Étape : Création du Projet

Étape 1 : Préparation des scripts Python

  1. init_db.py : Ce script crée la structure de la base de données et insère des données de test. Il s'assure que le dossier de données existe.
  2. mcp_server_db.py : C'est le cœur du serveur.
    • Il utilise FastMCP pour exposer deux outils : get_db_schema (pour que l'IA comprenne la structure) et run_query (pour exécuter le SQL).
    • Sécurité : La connexion SQLite utilise le paramètre mode=ro pour garantir que l'IA ne peut pas modifier vos données.

Étape 2 : Configuration Docker

  1. Dockerfile :
    • Utilise une image Python légère.
    • Installe le SDK MCP.
    • Définit le point d'entrée qui initialise la base de données avant de lancer le serveur.
  2. docker-compose.yml :
    • Gère le montage du volume ./data pour que vous puissiez voir le fichier .db sur votre ordinateur.
    • Active stdin_open et tty, car le protocole MCP communique via les flux standards (stdio).
    • Important : Le script mcp_server_db.py importe init_db.py pour s'assurer que la base existe au démarrage sans polluer la sortie standard (stdout).

Étape 3 : Construction de l'image

Ouvrez un terminal dans le dossier du projet et lancez :

# Assurer les droits d'écriture sur le dossier de données pour l'initialisation
chmod -R 777 data/

# Construire l'image Docker
docker build -t mcp-sqlite-server .

4. Validation avec l'Inspecteur MCP

L'inspecteur est l'outil de test officiel. Il permet de vérifier que le JSON-RPC fonctionne bien sans l'interface de l'IA.

npx @modelcontextprotocol/inspector docker run -i --rm \
  -v /Users/pierrejaumier/Developer/mcp-server-db/data:/app/data \
  -e DB_PATH=/app/data/test.db \
  mcp-sqlite-server

Scénarios de tests recommandés :

  • A. Découverte du schéma : Utilisez get_db_schema. Vous devez voir les structures CREATE TABLE. C'est ce qui permet à l'IA de "comprendre" la DB.
  • B. Requête simple : run_query avec {"sql_query": "SELECT * FROM users;"}.
  • C. Requête avec jointure : {"sql_query": "SELECT u.nom, o.produit FROM users u JOIN orders o ON u.id = o.user_id;"}
  • D. Sécurité (Lecture seule) : Essayez DELETE FROM users WHERE id = 1;. Vous devez recevoir une erreur readonly database.
  • E. Auto-correction : Faites une faute de frappe (SELECT * FORM users;). L'erreur retournée permettra à l'IA de se corriger seule.
  • F. Colonne inexistante : SELECT age FROM users;. L'erreur no such column forcera l'IA à re-consulter le schéma.

5. Utilisation avec Gemini CLI

Pour interroger votre base depuis votre terminal, configurez le serveur dans le CLI.

Ajouter le serveur (Chemins absolus obligatoires)

gemini mcp add sqlite-db --transport stdio docker run -i --rm \
  -v /Users/pierrejaumier/Developer/mcp-server-db/data:/app/data \
  -e DB_PATH=/app/data/test.db \
  mcp-sqlite-server

Lister les serveurs MCP accessibles pour gemini

gemini mcp list

Exemples de requêtes

  • gemini --prompt "Quels sont les utilisateurs dans ma base ?"
  • gemini --prompt "Calcule le montant total des commandes de Bob Leponge en utilisant sqlite-db."

6. Intégration VS Code (Gemini Code Assist)

  1. Ouvrez les Settings (JSON) de VS Code.
  2. Ajoutez ou modifiez la clé google.gemini.mcpServers :
"google.gemini.mcpServers": {
    "sqlite-db": {
        "command": "docker",
        "args": [
            "run",
            "-i",
            "--rm",
            "-v",
            "/Users/pierrejaumier/Developer/mcp-server-db/data:/app/data",
            "-e", "DB_PATH=/app/data/test.db",
            "mcp-sqlite-server"
        ]
    }
}

7. Dépannage

  • Statut Disconnected : C'est normal dans gemini mcp list car le conteneur s'arrête dès qu'il a fini sa tâche. Testez avec une vraie question.
  • Erreur Stdio : Assurez-vous que votre code Python utilise sys.stderr pour le logging. Tout print() sur stdout cassera la communication avec l'IA.
  • Logs Docker : Si rien ne se passe, lancez docker compose logs pour voir si le conteneur a planté au démarrage.

8. Utilisation avec Mistral Vibe

Pour connecter votre serveur MCP à Mistral Vibe et permettre à l'IA d'interroger votre base de données SQLite :

Configuration du serveur MCP

Comment configurer un serveur MCP avec Mistral Vibe ? La configuration se fait via le fichier ~/.vibe/config.toml. Voici ce qu'il faut ajouter à la place de mcp_servers = [] :

[[mcp_servers]]
name = "sqlite-db"
transport = "stdio"
command = "docker"
args = [
    "compose",
    "-f",
    "/home/neo/Developer/mcp-server-db/docker-compose.yml",
    "run",
    "--rm",
    "-i",
    "mcp-server",
]

Remplacez /home/neo/Developer/mcp-server-db par le chemin absolu de votre projet.

Exemples d'utilisation

Une fois le serveur ajouté, vous pouvez poser des questions en langage naturel :

  • "Quels sont les utilisateurs enregistrés dans ma base de données ?"
  • "Affiche-moi toutes les commandes de plus de 500€."
  • "Quel est le montant total des commandes de Bob Leponge ?"
  • "Qui a passé la commande la plus chère ?"

Mistral Vibe utilisera automatiquement les outils get_db_schema et run_query pour :

  1. Comprendre la structure de votre base de données
  2. Exécuter les requêtes SQL appropriées
  3. Vous retourner les résultats formatés

Astuces

  • Chemin absolu obligatoire : Docker nécessite des chemins absolus pour le montage de volume (-v).
  • Utilisez run et non up : docker compose up pollue la sortie standard avec des logs de création, ce qui casse le protocole MCP. run --rm -i est la commande correcte.
  • Mode lecture seule : Votre serveur est configuré en lecture seule (mode=ro), l'IA ne peut pas modifier vos données.
  • ** Persistance** : Les données dans ./data/test.db sont conservées entre les sessions grâce au volume Docker.
Ver o original no GitHub

Bom para

Relacionados