MotherDuck

Serveur MCP local DuckDB / MotherDuck

Analytique SQL et ingénierie des données pour assistants IA et IDE.

Connectez les assistants IA à vos données grâce au puissant moteur SQL analytique de DuckDB. Prend en charge la connexion à des fichiers DuckDB locaux, des bases en mémoire, des bases hébergées sur S3 et MotherDuck. Permet d'exécuter des requêtes SQL en lecture et en écriture, de parcourir les catalogues de bases de données et de basculer entre différentes connexions de bases de données à la volée.

Vous cherchez un serveur MCP distant entièrement géré pour MotherDuck ? → Consultez la documentation MCP distante de MotherDuck

MCP distant vs MCP local

Démarrage rapide

Prérequis : Installez uv via pip install uv ou brew install uv

Connexion à DuckDB en mémoire (mode développement)

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

Flexibilité totale sans garde-fous — accès en lecture-écriture et possibilité de basculer vers n'importe quelle base (fichiers locaux, S3 ou MotherDuck) à l'exécution.

Connexion à un fichier DuckDB local en mode lecture seule

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

Se connecte à un fichier DuckDB spécifique en mode lecture seule. Ne conserve pas le verrou de fichier, ce qui est pratique pour une utilisation parallèle à une connexion en écriture vers le même fichier DuckDB. Vous pouvez également vous connecter à des fichiers DuckDB distants sur S3 en utilisant s3://bucket/path.duckdb — voir Variables d'environnement pour l'authentification S3. Si vous envisagez un accès tiers au MCP, consultez Sécurisation pour la production.

Connexion à MotherDuck en mode lecture-écriture

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Consultez Paramètres de ligne de commande pour plus d'options, Sécurisation pour la production pour les recommandations de déploiement, et Dépannage en cas de problèmes.

Configuration du client

Client	Emplacement de configuration	Installation en un clic
Claude Desktop	Paramètres → Développeur → Modifier la configuration	.mcpb (MCP Bundle)
Claude Code	Utilisez les commandes CLI ci-dessous	-
Codex CLI	Utilisez les commandes CLI ci-dessous ou ~/.codex/config.toml	-
Gemini CLI	Utilisez les commandes CLI ci-dessous ou ~/.gemini/settings.json	-
Cursor	Paramètres → MCP → Ajouter un nouveau serveur MCP global
VS Code	Ctrl+Shift+P → "Préférences : Ouvrir les paramètres utilisateur (JSON)"
Kiro	~/.kiro/settings/mcp.json (global) ou .kiro/settings/mcp.json (projet)

Tout client compatible MCP peut utiliser ce serveur. Ajoutez la configuration JSON du Démarrage rapide au fichier de configuration MCP de votre client. Consultez la documentation de votre client pour connaître l'emplacement du fichier de configuration.

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

claude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

codex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

gemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Outils

*Nécessite le drapeau --allow-switch-databases

Tous les outils renvoient du JSON. Les résultats sont limités à 1024 lignes / 50 000 caractères par défaut (configurable via --max-rows, --max-chars).

Sécurisation pour la production

Lorsque vous donnez accès à des tiers à un serveur MCP auto-hébergé, le mode lecture seule seul ne suffit pas — il permet toujours l'accès au système de fichiers local, la modification des paramètres DuckDB et d'autres opérations potentiellement sensibles.

Pour les déploiements en production avec accès tiers, nous recommandons MotherDuck Remote MCP — zéro configuration, lecture-écriture prise en charge, et hébergé par MotherDuck.

Auto-hébergement du MCP MotherDuck : Forkez ce dépôt et personnalisez-le selon vos besoins. Utilisez un compte de service avec des jetons de lecture évolutifs et activez le mode SaaS pour restreindre l'accès aux fichiers locaux.

Auto-hébergement du MCP DuckDB : Utilisez --init-sql pour appliquer les paramètres de sécurité. Consultez le guide de sécurisation DuckDB pour les options disponibles.

Docker

Construisez et exécutez le serveur avec Streamable HTTP sur le port 8000 (par défaut, DuckDB en mémoire) :

docker build -t mcp-server-motherduck .
docker run --rm -p 8000:8000 mcp-server-motherduck

Connectez-vous à MotherDuck en passant un jeton et en remplaçant la commande :

docker run --rm -p 8000:8000 \
  -e motherduck_token="$MOTHERDUCK_TOKEN" \
  mcp-server-motherduck --transport http --db-path md:

Le point de terminaison MCP est disponible à http://localhost:8000/mcp. Les drapeaux CLI et les variables d'environnement ci-dessous s'appliquent toujours.

Paramètres de ligne de commande

Variables d'environnement

Dépannage

• spawn uvx ENOENT : Spécifiez le chemin complet vers uvx (exécutez which uvx pour le trouver)
• Fichier verrouillé : Assurez-vous que --ephemeral-connections est activé (défaut : true) et que vous n'êtes pas connecté en mode lecture-écriture

Ressources

• Documentation MCP MotherDuck
• Close the Loop : Des pipelines de données plus rapides avec MCP, DuckDB et IA (Blog)
• Des pipelines de données plus rapides avec MCP et DuckDB (YouTube)

Développement

Pour exécuter depuis la source :

{
  "mcpServers": {
    "Local DuckDB (Dev)": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Processus de publication

1. Exécutez l'action GitHub Release New Version
2. Saisissez la version au format MAJOR.MINOR.PATCH
3. Le workflow incrémente la version, publie sur PyPI/le registre MCP et crée la publication GitHub avec le package MCPB

Licence

Licence MIT - voir le fichier LICENSE.

mcp-name: io.github.motherduckdb/mcp-server-motherduck