MotherDuck

DuckDB / MotherDuck Local MCP Server

Phân tích SQL và kỹ thuật dữ liệu cho Trợ lý AI và IDE.

Kết nối trợ lý AI với dữ liệu của bạn bằng công cụ SQL phân tích mạnh mẽ của DuckDB. Hỗ trợ kết nối đến các tệp DuckDB cục bộ, cơ sở dữ liệu trong bộ nhớ, cơ sở dữ liệu lưu trữ trên S3 và MotherDuck. Cho phép thực thi các truy vấn SQL đọc và ghi, duyệt danh mục cơ sở dữ liệu và chuyển đổi giữa các kết nối cơ sở dữ liệu khác nhau một cách linh hoạt.

Đang tìm kiếm máy chủ MCP từ xa được quản lý hoàn toàn cho MotherDuck? → Truy cập tài liệu MotherDuck Remote MCP

Remote MCP so với Local MCP

Bắt đầu nhanh

Điều kiện tiên quyết: Cài đặt uv qua pip install uv hoặc brew install uv

Kết nối đến DuckDB trong bộ nhớ (Chế độ Dev)

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

Linh hoạt hoàn toàn không có rào cản — truy cập đọc-ghi và khả năng chuyển sang bất kỳ cơ sở dữ liệu nào (tệp cục bộ, S3 hoặc MotherDuck) trong thời gian chạy.

Kết nối đến tệp DuckDB cục bộ ở chế độ chỉ đọc

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

Kết nối đến một tệp DuckDB cụ thể ở chế độ chỉ đọc. Không giữ khóa tệp, do đó thuận tiện khi sử dụng cùng với kết nối ghi đến cùng tệp DuckDB. Bạn cũng có thể kết nối đến các tệp DuckDB từ xa trên S3 bằng s3://bucket/path.duckdb — xem Biến môi trường để xác thực S3. Nếu bạn đang cân nhắc truy cập của bên thứ ba vào MCP, hãy xem Bảo mật cho sản xuất.

Kết nối đến MotherDuck ở chế độ đọc-ghi

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

Xem Tham số dòng lệnh để biết thêm tùy chọn, Bảo mật cho sản xuất để biết hướng dẫn triển khai và Khắc phục sự cố nếu bạn gặp sự cố.

Thiết lập máy khách

Máy khách	Vị trí cấu hình	Cài đặt một cú nhấp chuột
Claude Desktop	Cài đặt → Nhà phát triển → Chỉnh sửa cấu hình	.mcpb (Gói MCP)
Claude Code	Sử dụng lệnh CLI bên dưới	-
Codex CLI	Sử dụng lệnh CLI bên dưới hoặc ~/.codex/config.toml	-
Gemini CLI	Sử dụng lệnh CLI bên dưới hoặc ~/.gemini/settings.json	-
Cursor	Cài đặt → MCP → Thêm máy chủ MCP toàn cục mới
VS Code	Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"
Kiro	~/.kiro/settings/mcp.json (toàn cục) hoặc .kiro/settings/mcp.json (dự án)

Bất kỳ máy khách tương thích MCP nào cũng có thể sử dụng máy chủ này. Thêm cấu hình JSON từ Bắt đầu nhanh vào tệp cấu hình MCP của máy khách. Tham khảo tài liệu của máy khách để biết vị trí tệp cấu hình.

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

Công cụ

*Yêu cầu cờ --allow-switch-databases

Tất cả công cụ trả về JSON. Kết quả được giới hạn ở 1024 hàng / 50.000 ký tự theo mặc định (có thể cấu hình qua --max-rows, --max-chars).

Bảo mật cho sản xuất

Khi cấp quyền truy cập cho bên thứ ba vào máy chủ MCP tự lưu trữ, chế độ chỉ đọc một mình là không đủ — nó vẫn cho phép truy cập vào hệ thống tệp cục bộ, thay đổi cài đặt DuckDB và các thao tác nhạy cảm tiềm ẩn khác.

Đối với triển khai sản xuất với quyền truy cập của bên thứ ba, chúng tôi khuyên dùng MotherDuck Remote MCP — không cần thiết lập, hỗ trợ đọc-ghi và được lưu trữ bởi MotherDuck.

Tự lưu trữ MotherDuck MCP: Fork kho lưu trữ này và tùy chỉnh khi cần. Sử dụng tài khoản dịch vụ với mã thông báo mở rộng đọc và bật chế độ SaaS để hạn chế truy cập tệp cục bộ.

Tự lưu trữ DuckDB MCP: Sử dụng --init-sql để áp dụng cài đặt bảo mật. Xem hướng dẫn Bảo mật DuckDB để biết các tùy chọn có sẵn.

Docker

Xây dựng và chạy máy chủ với Streamable HTTP trên cổng 8000 (mặc định là DuckDB trong bộ nhớ):

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

Kết nối đến MotherDuck bằng cách truyền mã thông báo và ghi đè lệnh:

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

Điểm cuối MCP có sẵn tại http://localhost:8000/mcp. Các cờ CLI và biến env bên dưới vẫn được áp dụng.

Tham số dòng lệnh

Biến môi trường

Khắc phục sự cố

• spawn uvx ENOENT: Chỉ định đường dẫn đầy đủ đến uvx (chạy which uvx để tìm)
• Tệp bị khóa: Đảm bảo --ephemeral-connections được bật (mặc định: true) và bạn không kết nối ở chế độ đọc-ghi

Tài nguyên

• Tài liệu MotherDuck MCP
• Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blog)
• Faster Data Pipelines with MCP and DuckDB (YouTube)

Phát triển

Để chạy từ mã nguồn:

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

Quy trình phát hành

1. Chạy GitHub Action Release New Version
2. Nhập phiên bản ở định dạng MAJOR.MINOR.PATCH
3. Quy trình làm việc tăng phiên bản, xuất bản lên PyPI/đăng ký MCP và tạo bản phát hành GitHub với gói MCPB

Giấy phép

Giấy phép MIT - xem tệp LICENSE.

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