MotherDuck

DuckDB / MotherDuck Local MCP Server

Analitik SQL dan rekayasa data untuk Asisten AI dan IDE.

Hubungkan asisten AI ke data Anda menggunakan mesin SQL analitik DuckDB yang kuat. Mendukung koneksi ke file DuckDB lokal, database dalam memori, database yang dihosting di S3, dan MotherDuck. Memungkinkan eksekusi query SQL baca dan tulis, menjelajahi katalog database, dan berpindah antar koneksi database yang berbeda secara langsung.

Mencari server MCP jarak jauh yang dikelola penuh untuk MotherDuck? → Buka dokumentasi MotherDuck Remote MCP

Remote vs Local MCP

Mulai Cepat

Prasyarat: Instal uv melalui pip install uv atau brew install uv

Menghubungkan ke DuckDB Dalam Memori (Mode Dev)

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

Fleksibilitas penuh tanpa pengaman — akses baca-tulis dan kemampuan untuk berpindah ke database mana pun (file lokal, S3, atau MotherDuck) saat runtime.

Menghubungkan ke File DuckDB Lokal dalam Mode Hanya-Baca

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

Menghubungkan ke file DuckDB tertentu dalam mode hanya-baca. Tidak akan memegang kunci file, sehingga nyaman digunakan bersama koneksi tulis ke file DuckDB yang sama. Anda juga dapat terhubung ke file DuckDB jarak jauh di S3 menggunakan s3://bucket/path.duckdb — lihat Variabel Lingkungan untuk autentikasi S3. Jika Anda mempertimbangkan akses pihak ketiga ke MCP, lihat Mengamankan untuk Produksi.

Menghubungkan ke MotherDuck dalam Mode Baca-Tulis

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

Lihat Parameter Baris Perintah untuk opsi lainnya, Mengamankan untuk Produksi untuk panduan penerapan, dan Pemecahan Masalah jika Anda mengalami masalah.

Pengaturan Klien

Klien	Lokasi Konfigurasi	Instalasi Satu-Klik
Claude Desktop	Pengaturan → Pengembang → Edit Konfigurasi	.mcpb (MCP Bundle)
Claude Code	Gunakan perintah CLI di bawah	-
Codex CLI	Gunakan perintah CLI di bawah atau ~/.codex/config.toml	-
Gemini CLI	Gunakan perintah CLI di bawah atau ~/.gemini/settings.json	-
Cursor	Pengaturan → MCP → Tambahkan server MCP global baru
VS Code	Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"
Kiro	~/.kiro/settings/mcp.json (global) atau .kiro/settings/mcp.json (proyek)

Klien apa pun yang kompatibel dengan MCP dapat menggunakan server ini. Tambahkan konfigurasi JSON dari Mulai Cepat ke file konfigurasi MCP klien Anda. Konsultasikan dokumentasi klien Anda untuk lokasi file konfigurasi.

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>"
      }
    }
  }
}

Alat

*Memerlukan flag --allow-switch-databases

Semua alat mengembalikan JSON. Hasil dibatasi hingga 1024 baris / 50.000 karakter secara default (dapat dikonfigurasi melalui --max-rows, --max-chars).

Mengamankan untuk Produksi

Saat memberikan akses pihak ketiga ke server MCP yang di-host sendiri, mode hanya-baca saja tidak cukup — mode ini masih memungkinkan akses ke sistem file lokal, mengubah pengaturan DuckDB, dan operasi sensitif lainnya.

Untuk penerapan produksi dengan akses pihak ketiga, kami merekomendasikan MotherDuck Remote MCP — tanpa pengaturan, mampu baca-tulis, dan dihosting oleh MotherDuck.

Self-hosting MotherDuck MCP: Fork repo ini dan sesuaikan sesuai kebutuhan. Gunakan akun layanan dengan token penskalaan-baca dan aktifkan mode SaaS untuk membatasi akses file lokal.

Self-hosting DuckDB MCP: Gunakan --init-sql untuk menerapkan pengaturan keamanan. Lihat panduan Mengamankan DuckDB untuk opsi yang tersedia.

Docker

Bangun dan jalankan server dengan Streamable HTTP di port 8000 (default ke DuckDB dalam memori):

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

Hubungkan ke MotherDuck dengan meneruskan token dan menimpa perintah:

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

Endpoint MCP tersedia di http://localhost:8000/mcp. Flag CLI dan variabel env dari bawah masih berlaku.

Parameter Baris Perintah

Variabel Lingkungan

Pemecahan Masalah

• spawn uvx ENOENT: Tentukan jalur lengkap ke uvx (jalankan which uvx untuk menemukannya)
• File terkunci: Pastikan --ephemeral-connections diaktifkan (default: true) dan Anda tidak terhubung dalam mode baca-tulis

Sumber Daya

• Dokumentasi MCP MotherDuck
• Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blog)
• Faster Data Pipelines with MCP and DuckDB (YouTube)

Pengembangan

Untuk menjalankan dari sumber:

{
  "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>"
      }
    }
  }
}

Proses Rilis

1. Jalankan Release New Version GitHub Action
2. Masukkan versi dalam format MAJOR.MINOR.PATCH
3. Alur kerja menaikkan versi, memublikasikan ke PyPI/registri MCP, dan membuat rilis GitHub dengan paket MCPB

Lisensi

Lisensi MIT - lihat file LICENSE.

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