MotherDuck MCP Server

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 DuckDB yang tangguh. 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 langsung.

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

MCP Jarak Jauh vs Lokal

📝 Migrasi 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.
• MotherDuck hanya-baca memerlukan token skala-baca: Koneksi MotherDuck dalam mode hanya-baca memerlukan token skala-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 otentikasi 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 (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 → Tambah 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. 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 dihosting sendiri, mode hanya-baca saja tidak cukup — mode ini masih memungkinkan akses ke sistem file lokal, mengubah pengaturan DuckDB, dan operasi lain yang berpotensi sensitif.

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 skala-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.

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
• Tutup 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 menaikkan versi, menerbitkan 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