MotherDuck MCP Server

DuckDB / MotherDuck Local MCP Server

การวิเคราะห์ SQL และวิศวกรรมข้อมูลสำหรับผู้ช่วย AI และ IDE

เชื่อมต่อผู้ช่วย AI เข้ากับข้อมูลของคุณโดยใช้กลไก SQL วิเคราะห์อันทรงพลังของ DuckDB รองรับการเชื่อมต่อกับไฟล์ DuckDB ในเครื่อง, ฐานข้อมูลในหน่วยความจำ, ฐานข้อมูลที่โฮสต์บน S3 และ MotherDuck อนุญาตให้ดำเนินการคำสั่ง SQL แบบอ่านและเขียน, เรียกดูแคตตาล็อกฐานข้อมูล และสลับระหว่างการเชื่อมต่อฐานข้อมูลต่างๆ ได้ทันที

กำลังมองหาเซิร์ฟเวอร์ MCP ระยะไกลที่มีการจัดการเต็มรูปแบบสำหรับ MotherDuck อยู่หรือไม่? → ไปที่เอกสาร MotherDuck Remote MCP

Remote vs Local MCP

📝 กำลังย้ายจาก v0.x?

• อ่านอย่างเดียวโดยค่าเริ่มต้น: ขณะนี้เซิร์ฟเวอร์ทำงานในโหมดอ่านอย่างเดียวโดยค่าเริ่มต้น เพิ่ม --read-write เพื่อเปิดใช้งานการเข้าถึงแบบเขียน ดู การรักษาความปลอดภัยสำหรับการใช้งานจริง
• ฐานข้อมูลเริ่มต้นเปลี่ยนไป: ค่าเริ่มต้น --db-path เปลี่ยนจาก md: เป็น :memory: เพิ่ม --db-path md: อย่างชัดเจนสำหรับ MotherDuck
• MotherDuck แบบอ่านอย่างเดียวต้องใช้โทเค็น read-scaling: การเชื่อมต่อ MotherDuck ในโหมดอ่านอย่างเดียวต้องใช้ โทเค็น read-scaling โทเค็นปกติต้องใช้ --read-write

เริ่มต้นอย่างรวดเร็ว

ข้อกำหนดเบื้องต้น: ติดตั้ง uv ผ่าน pip install uv หรือ brew install uv

การเชื่อมต่อกับ DuckDB ในหน่วยความจำ (โหมดพัฒนา)

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

ความยืดหยุ่นเต็มรูปแบบโดยไม่มีข้อจำกัด — การเข้าถึงแบบอ่าน-เขียนและความสามารถในการสลับไปยังฐานข้อมูลใดๆ (ไฟล์ในเครื่อง, S3 หรือ MotherDuck) ณ รันไทม์

การเชื่อมต่อกับไฟล์ DuckDB ในเครื่องในโหมดอ่านอย่างเดียว

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

เชื่อมต่อกับไฟล์ DuckDB เฉพาะในโหมดอ่านอย่างเดียว จะไม่ล็อกไฟล์ไว้ จึงสะดวกที่จะใช้ร่วมกับการเชื่อมต่อแบบเขียนไปยังไฟล์ DuckDB เดียวกัน คุณยังสามารถเชื่อมต่อกับไฟล์ DuckDB ระยะไกลบน S3 โดยใช้ s3://bucket/path.duckdb — ดู ตัวแปรสภาพแวดล้อม สำหรับการรับรองความถูกต้อง S3 หากคุณกำลังพิจารณาการเข้าถึง MCP โดยบุคคลที่สาม ดู การรักษาความปลอดภัยสำหรับการใช้งานจริง

การเชื่อมต่อกับ MotherDuck ในโหมดอ่าน-เขียน

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

ดู พารามิเตอร์บรรทัดคำสั่ง สำหรับตัวเลือกเพิ่มเติม, การรักษาความปลอดภัยสำหรับการใช้งานจริง สำหรับคำแนะนำในการปรับใช้ และ การแก้ไขปัญหา หากคุณพบปัญหา

การตั้งค่าไคลเอนต์

ไคลเอนต์	ตำแหน่งการกำหนดค่า	ติดตั้งในคลิกเดียว
Claude Desktop	Settings → Developer → Edit Config	.mcpb (MCP Bundle)
Claude Code	ใช้คำสั่ง CLI ด้านล่าง	-
Codex CLI	ใช้คำสั่ง CLI ด้านล่างหรือ ~/.codex/config.toml	-
Gemini CLI	ใช้คำสั่ง CLI ด้านล่างหรือ ~/.gemini/settings.json	-
Cursor	Settings → MCP → Add new global MCP server
VS Code	Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"
Kiro	~/.kiro/settings/mcp.json (global) หรือ .kiro/settings/mcp.json (project)

ไคลเอนต์ที่เข้ากันได้กับ MCP ใดๆ สามารถใช้เซิร์ฟเวอร์นี้ได้ เพิ่มการกำหนดค่า JSON จาก เริ่มต้นอย่างรวดเร็ว ลงในไฟล์กำหนดค่า MCP ของไคลเอนต์ของคุณ ศึกษาเอกสารของไคลเอนต์ของคุณสำหรับตำแหน่งไฟล์กำหนดค่า

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

เครื่องมือ

*ต้องใช้แฟล็ก --allow-switch-databases

เครื่องมือทั้งหมดส่งคืน JSON ผลลัพธ์ถูกจำกัดที่ 1024 แถว / 50,000 ตัวอักษรโดยค่าเริ่มต้น (กำหนดค่าได้ผ่าน --max-rows, --max-chars)

การรักษาความปลอดภัยสำหรับการใช้งานจริง

เมื่อให้บุคคลที่สามเข้าถึงเซิร์ฟเวอร์ MCP ที่โฮสต์เอง โหมดอ่านอย่างเดียวเพียงอย่างเดียวไม่เพียงพอ — มันยังคงอนุญาตให้เข้าถึงระบบไฟล์ในเครื่อง, เปลี่ยนการตั้งค่า DuckDB และการดำเนินการที่อาจละเอียดอ่อนอื่นๆ

สำหรับการปรับใช้ในการใช้งานจริงที่มีการเข้าถึงโดยบุคคลที่สาม เราขอแนะนำ MotherDuck Remote MCP — ไม่ต้องตั้งค่า, รองรับการอ่าน-เขียน และโฮสต์โดย MotherDuck

การโฮสต์ MotherDuck MCP ด้วยตนเอง: Fork repo นี้และปรับแต่งตามต้องการ ใช้ บัญชีบริการ พร้อม โทเค็น read-scaling และเปิดใช้งาน โหมด SaaS เพื่อจำกัดการเข้าถึงไฟล์ในเครื่อง

การโฮสต์ DuckDB MCP ด้วยตนเอง: ใช้ --init-sql เพื่อใช้การตั้งค่าความปลอดภัย ดู คู่มือการรักษาความปลอดภัย DuckDB สำหรับตัวเลือกที่มี

พารามิเตอร์บรรทัดคำสั่ง

ตัวแปรสภาพแวดล้อม

การแก้ไขปัญหา

• spawn uvx ENOENT: ระบุพาธเต็มไปยัง uvx (รัน which uvx เพื่อค้นหา)
• ไฟล์ถูกล็อก: ตรวจสอบให้แน่ใจว่า --ephemeral-connections เปิดอยู่ (ค่าเริ่มต้น: true) และคุณไม่ได้เชื่อมต่อในโหมดอ่าน-เขียน

แหล่งข้อมูล

• เอกสาร MotherDuck MCP
• Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (บล็อก)
• Faster Data Pipelines with MCP and DuckDB (YouTube)

การพัฒนา

เพื่อรันจากซอร์ส:

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

กระบวนการเผยแพร่

1. รัน GitHub Action Release New Version
2. ป้อนเวอร์ชันในรูปแบบ MAJOR.MINOR.PATCH
3. เวิร์กโฟลว์จะเพิ่มเวอร์ชัน, เผยแพร่ไปยัง PyPI/MCP registry และสร้าง GitHub release พร้อมแพ็คเกจ MCPB

ใบอนุญาต

ใบอนุญาต MIT - ดูไฟล์ LICENSE

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