MotherDuck

Serveur MCP local DuckDB / MotherDuck

Analyse SQL et ingénierie de données pour les assistants IA et les IDE.

Connectez les assistants IA à vos données en utilisant le puissant moteur SQL analytique de DuckDB. Prend en charge la connexion aux fichiers DuckDB locaux, aux bases de données en mémoire, aux bases de données 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 base de données à la volée.

Vous recherchez un serveur MCP distant entièrement géré pour MotherDuck ? → Consultez la documentation du MCP distant MotherDuck

MCP distant vs local

📝 Migration depuis la v0.x ?

• Lecture seule par défaut : Le serveur fonctionne désormais en mode lecture seule par défaut. Ajoutez --read-write pour activer l'accès en écriture. Voir Sécurisation pour la production.
• Base de données par défaut modifiée : La valeur par défaut de --db-path est passée de md: à :memory:. Ajoutez --db-path md: explicitement pour MotherDuck.
• La lecture seule MotherDuck nécessite un jeton de lecture à l'échelle : Les connexions MotherDuck en mode lecture seule nécessitent un jeton de lecture à l'échelle. Les jetons standard nécessitent --read-write.

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 de données (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 conservera pas le verrou de fichier, ce qui est pratique pour une utilisation conjointe avec une connexion en écriture au 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>"
      }
    }
  }
}

Voir Paramètres de ligne de commande pour plus d'options, Sécurisation pour la production pour des conseils de déploiement, et Dépannage si vous rencontrez des problèmes.

Configuration du client

Client	Emplacement de la configuration	Installation en un clic
Claude Desktop	Paramètres → Développeur → Modifier la configuration	.mcpb (Bundle MCP)
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 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 à des tiers l'accès à un serveur MCP auto-hébergé, le mode lecture seule seul n'est pas suffisant — 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 — aucune configuration, capable de lecture-écriture, et hébergé par MotherDuck.

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

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

Docker

Construisez et exécutez le serveur avec HTTP Streamable sur le port 8000 (par défaut, une base 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 à l'adresse 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é (par défaut : true) et que vous n'êtes pas connecté en mode lecture-écriture

Ressources

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

Développement

Pour exécuter à partir des sources :

{
  "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 version GitHub avec le package MCPB

Licence

Licence MIT - voir le fichier LICENSE.

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