MotherDuck

Server MCP Lokal DuckDB / MotherDuck

Analitik SQL dan rekayasa data untuk Asisten AI dan IDE.

Hubungkan asisten AI ke data Anda menggunakan mesin SQL analitik canggih DuckDB. Mendukung koneksi ke file DuckDB lokal, basis data dalam memori, basis data yang dihosting di S3, dan MotherDuck. Memungkinkan eksekusi kueri baca dan tulis SQL, menjelajahi katalog basis data, dan beralih di antara koneksi basis data yang berbeda secara dinamis.

Mencari server MCP jarak jauh yang dikelola sepenuhnya untuk MotherDuck? → Buka dokumen MCP Jarak Jauh MotherDuck

MCP Jarak Jauh vs Lokal

📝 Bermigrasi dari v0.x?

• Hanya-baca secara default: Server sekarang berjalan dalam mode hanya-baca secara default. Tambahkan --read-write untuk mengaktifkan akses tulis. Lihat Mengamankan untuk Produksi.
• Basis data default berubah: Default --db-path berubah dari md: menjadi :memory:. Tambahkan --db-path md: secara eksplisit untuk MotherDuck.
• Mode hanya-baca MotherDuck memerlukan token penskalaan baca: Koneksi MotherDuck dalam mode hanya-baca memerlukan token penskalaan baca. Token biasa memerlukan --read-write.

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 pagar pembatas — akses baca-tulis dan kemampuan untuk beralih ke basis data apa 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"]
    }
  }
}

Terhubung ke file DuckDB tertentu dalam mode hanya-baca. Tidak akan menahan 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.

Penyiapan Klien

Klien	Lokasi Konfigurasi	Instal Sekali Klik
Claude Desktop	Pengaturan → Pengembang → Edit Konfigurasi	.mcpb (Paket MCP)
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 → "Preferensi: Buka Pengaturan Pengguna (JSON)"
Kiro	~/.kiro/settings/mcp.json (global) atau .kiro/settings/mcp.json (proyek)

Setiap klien yang kompatibel dengan MCP dapat menggunakan server ini. Tambahkan konfigurasi JSON dari Mulai Cepat ke file konfigurasi MCP klien Anda. Lihat 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 dihosting sendiri, mode hanya-baca saja tidak cukup — mode ini masih memungkinkan akses ke sistem file lokal, mengubah pengaturan DuckDB, dan operasi sensitif potensial lainnya.

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

Menghosting sendiri MCP MotherDuck: Fork repositori ini dan sesuaikan sesuai kebutuhan. Gunakan akun layanan dengan token penskalaan baca dan aktifkan mode SaaS untuk membatasi akses file lokal.

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

Docker

Bangun dan jalankan server dengan HTTP Streamable pada 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 memberikan token dan mengganti perintah:

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

Titik akhir MCP tersedia di http://localhost:8000/mcp. Flag CLI dan variabel lingkungan 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: Pipeline Data Lebih Cepat dengan MCP, DuckDB & AI (Blog)
• Pipeline Data Lebih Cepat dengan MCP dan 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 GitHub Action Release New Version
2. Masukkan versi dalam format MAJOR.MINOR.PATCH
3. Alur kerja meningkatkan versi, menerbitkan ke registri PyPI/MCP, dan membuat rilis GitHub dengan paket MCPB

Lisensi

Lisensi MIT - lihat file LICENSE.

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