MotherDuck MCP Server

DuckDB / MotherDuck Yerel MCP Sunucusu

Yapay Zeka Asistanları ve IDE'ler için SQL analitiği ve veri mühendisliği.

DuckDB'nin güçlü analitik SQL motorunu kullanarak yapay zeka asistanlarınızı verilerinize bağlayın. Yerel DuckDB dosyalarına, bellek içi veritabanlarına, S3'te barındırılan veritabanlarına ve MotherDuck'a bağlanmayı destekler. SQL okuma ve yazma sorguları çalıştırmaya, veritabanı kataloglarına göz atmaya ve farklı veritabanı bağlantıları arasında anında geçiş yapmaya olanak tanır.

MotherDuck için tam yönetilen uzak MCP sunucusu mu arıyorsunuz? → MotherDuck Uzak MCP belgelerine gidin

Uzak ve Yerel MCP Karşılaştırması

📝 v0.x sürümünden mi geçiş yapıyorsunuz?

• Varsayılan olarak salt okunur: Sunucu artık varsayılan olarak salt okunur modda çalışır. Yazma erişimini etkinleştirmek için --read-write ekleyin. Üretim için Güvenlik bölümüne bakın.
• Varsayılan veritabanı değişti: --db-path varsayılanı md: yerine :memory: olarak değiştirildi. MotherDuck için açıkça --db-path md: ekleyin.
• MotherDuck salt okunur modu, okuma ölçeklendirme jetonu gerektirir: Salt okunur moddaki MotherDuck bağlantıları bir okuma ölçeklendirme jetonu gerektirir. Normal jetonlar --read-write gerektirir.

Hızlı Başlangıç

Ön Koşullar: uv'i pip install uv veya brew install uv aracılığıyla yükleyin

Bellek İçi DuckDB'ye Bağlanma (Geliştirme Modu)

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

Koruma korkulukları olmadan tam esneklik — okuma-yazma erişimi ve çalışma zamanında herhangi bir veritabanına (yerel dosyalar, S3 veya MotherDuck) geçiş yapabilme yeteneği.

Salt Okunur Modda Yerel Bir DuckDB Dosyasına Bağlanma

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

Belirli bir DuckDB dosyasına salt okunur modda bağlanır. Dosya kilidini tutmaz, bu nedenle aynı DuckDB dosyasına yazma bağlantısıyla birlikte kullanımı uygundur. s3://bucket/path.duckdb kullanarak S3'teki uzak DuckDB dosyalarına da bağlanabilirsiniz — S3 kimlik doğrulaması için Ortam Değişkenleri bölümüne bakın. MCP'ye üçüncü taraf erişimi düşünüyorsanız, Üretim için Güvenlik bölümüne bakın.

Okuma-Yazma Modunda MotherDuck'a Bağlanma

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

Daha fazla seçenek için Komut Satırı Parametreleri, dağıtım rehberliği için Üretim için Güvenlik ve sorunlarla karşılaşırsanız Sorun Giderme bölümlerine bakın.

İstemci Kurulumu

İstemci	Yapılandırma Konumu	Tek Tıkla Kurulum
Claude Desktop	Ayarlar → Geliştirici → Yapılandırmayı Düzenle	.mcpb (MCP Paketi)
Claude Code	Aşağıdaki CLI komutlarını kullanın	-
Codex CLI	Aşağıdaki CLI komutlarını veya ~/.codex/config.toml kullanın	-
Gemini CLI	Aşağıdaki CLI komutlarını veya ~/.gemini/settings.json kullanın	-
Cursor	Ayarlar → MCP → Yeni genel MCP sunucusu ekle
VS Code	Ctrl+Shift+P → "Tercihler: Kullanıcı Ayarlarını Aç (JSON)"
Kiro	~/.kiro/settings/mcp.json (genel) veya .kiro/settings/mcp.json (proje)

MCP uyumlu herhangi bir istemci bu sunucuyu kullanabilir. Hızlı Başlangıç bölümündeki JSON yapılandırmasını istemcinizin MCP yapılandırma dosyasına ekleyin. Yapılandırma dosyasının konumu için istemcinizin belgelerine başvurun.

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

Araçlar

*--allow-switch-databases bayrağını gerektirir

Tüm araçlar JSON döndürür. Sonuçlar varsayılan olarak 1024 satır / 50.000 karakter ile sınırlıdır (--max-rows, --max-chars ile yapılandırılabilir).

Üretim için Güvenlik

Üçüncü taraflara self-hosted bir MCP sunucusuna erişim verirken, salt okunur mod tek başına yeterli değildir — yerel dosya sistemine erişime, DuckDB ayarlarını değiştirmeye ve diğer potansiyel olarak hassas işlemlere hâlâ izin verir.

Üçüncü taraf erişimi olan üretim dağıtımları için MotherDuck Uzak MCP'yi öneririz — sıfır kurulum, okuma-yazma yetenekli ve MotherDuck tarafından barındırılır.

MotherDuck MCP'yi self-hosted olarak kullanma: Bu repoyu çatallayın ve gerektiği gibi özelleştirin. Bir hizmet hesabı ile okuma ölçeklendirme jetonları kullanın ve yerel dosya erişimini kısıtlamak için SaaS modunu etkinleştirin.

DuckDB MCP'yi self-hosted olarak kullanma: Güvenlik ayarlarını uygulamak için --init-sql kullanın. Mevcut seçenekler için DuckDB Güvenlik Rehberi'ne bakın.

Komut Satırı Parametreleri

Ortam Değişkenleri

Sorun Giderme

• spawn uvx ENOENT: uvx tam yolunu belirtin (bulmak için which uvx çalıştırın)
• Dosya kilitli: --ephemeral-connections açık olduğundan (varsayılan: true) ve okuma-yazma modunda bağlı olmadığınızdan emin olun

Kaynaklar

• MotherDuck MCP Belgeleri
• Döngüyü Kapatın: MCP, DuckDB ve Yapay Zeka ile Daha Hızlı Veri İşlem Hatları (Blog)
• MCP ve DuckDB ile Daha Hızlı Veri İşlem Hatları (YouTube)

Geliştirme

Kaynaktan çalıştırmak için:

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

Sürüm Süreci

1. Release New Version GitHub Eylemini çalıştırın
2. Sürümü MAJOR.MINOR.PATCH biçiminde girin
3. İş akışı sürümü artırır, PyPI/MCP kayıt defterinde yayınlar ve MCPB paketiyle GitHub sürümünü oluşturur

Lisans

MIT Lisansı - LICENSE dosyasına bakın.

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