mcp-server-sqlite

Serveur MCP (Model Context Protocol) en Python exposant une base SQLite à un assistant IA via un unique outil : execute_sql. Usage local et personnel.

L'IA peut exécuter n'importe quelle requête SQL (SELECT, INSERT, UPDATE, DELETE, DDL…) et récupérer les résultats au format JSON.

⚠️ Aucun garde-fou de sécurité : le SQL est totalement libre, il n'y a ni mode lecture seule, ni authentification, ni limite. Destiné à un usage local par un utilisateur unique.

Prérequis

• Python 3.12+
• uv

Installation

uv sync

Lancement

Le chemin de la base SQLite est fourni via --db-path ou la variable d'environnement SQLITE_DB_PATH. Le fichier est créé automatiquement s'il n'existe pas.

Mode stdio (usage local standard)

uv run mcp-server-sqlite --db-path ./ma_base.db

Mode HTTP (JSON, sans SSE)

uv run mcp-server-sqlite --transport http --db-path ./ma_base.db --host 127.0.0.1 --port 8000

Le transport HTTP répond en application/json (pas de flux SSE), adapté aux clients incapables de streamer. Par défaut : 127.0.0.1:8000.

Accès navigateur : le serveur fonctionne sans aucune configuration d'origine. La protection anti DNS-rebinding du SDK MCP est désactivée (sinon les origines non-localhost sont rejetées avec « Invalid Origin header ») et le CORS autorise par défaut toutes les origines (*). Si vous souhaitez malgré tout restreindre le CORS, utilisez --cors-origin (répétable) :

uv run mcp-server-sqlite --transport http --cors-origin http://localhost:3000 --cors-origin https://mon-app.example

L'en-tête Mcp-Session-Id est exposé pour permettre aux clients navigateurs de lire l'identifiant de session MCP.

L'outil execute_sql

• Entrée : sql — une chaîne contenant du SQL arbitraire. Plusieurs instructions peuvent être séparées par ; (exécution de type executescript).
• Sortie (chaîne JSON) :
  • Requête renvoyant des lignes (SELECT) : {"rows": [{"colonne": valeur, ...}, ...]}
  • Requête de modification / DDL : {"rowcount": <nombre de lignes affectées>}
  • Erreur SQL : {"error": "<message>"}
• Les types non natifs JSON sont convertis en chaîne : BLOB décodé en UTF-8 (repli en hexadécimal), dates au format ISO.
• Commit automatique après chaque appel réussi.

Configuration côté client MCP

Deux cas de figure : le client lance lui-même le serveur (mode stdio), ou le client se connecte à un serveur HTTP déjà démarré.

Mode stdio (le client lance le serveur)

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "sqlite": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "d:/___AGENTS/mcp-server-sqlite-uv",
        "mcp-server-sqlite",
        "--db-path",
        "d:/___AGENTS/mcp-server-sqlite-uv/ma_base.db"
      ]
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "sqlite": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "d:/___AGENTS/mcp-server-sqlite-uv",
        "mcp-server-sqlite",
        "--db-path",
        "d:/___AGENTS/mcp-server-sqlite-uv/ma_base.db"
      ]
    }
  }
}

Mode HTTP (le serveur est démarré à part)

Démarrez d'abord le serveur en mode HTTP :

uv run mcp-server-sqlite --transport http --db-path ./ma_base.db --host 127.0.0.1 --port 8000

Le point de terminaison MCP est alors disponible sur http://127.0.0.1:8000/mcp. Configurez ensuite le client pour s'y connecter par URL.

VS Code (.vscode/mcp.json)

{
  "servers": {
    "sqlite": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Claude Desktop (claude_desktop_config.json)

Claude Desktop ne se connecte qu'en stdio ; on passe par le proxy mcp-remote pour atteindre un serveur HTTP :

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}

ℹ️ Si le client tourne dans un navigateur, autorisez son origine avec --cors-origin au lancement du serveur (voir la section Lancement).

Tests

uv run pytest

Développement avec mise

Le projet fournit un mise.toml qui gère les outils (Python 3.12, uv) et expose des tâches. uv est configuré pour utiliser le Python fourni par mise.

mise install       # installe Python + uv
mise run install   # uv sync
mise run test      # tests pytest
mise run serve     # serveur en mode stdio
mise run serve-http # serveur en mode HTTP (JSON)

Licence

MIT — voir LICENSE.