MotherDuck

Máy chủ MCP cục bộ DuckDB / MotherDuck

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 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 đọc và ghi SQL, 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.

Bạn đang tìm kiếm một máy chủ MCP từ xa được quản lý đầy đủ cho MotherDuck? → Đi tới tài liệu MCP từ xa của MotherDuck

MCP từ xa so với MCP cục bộ

📝 Đang chuyển từ v0.x?

• Mặc định chỉ đọc: Máy chủ hiện chạy ở chế độ chỉ đọc theo mặc định. Thêm --read-write để kích hoạt quyền ghi. Xem Bảo mật cho Sản xuất.
• Cơ sở dữ liệu mặc định đã thay đổi: --db-path mặc định đã thay đổi từ md: thành :memory:. Thêm --db-path md: một cách rõ ràng cho MotherDuck.
• Chỉ đọc MotherDuck yêu cầu mã thông báo đọc mở rộng: Kết nối MotherDuck ở chế độ chỉ đọc yêu cầu mã thông báo đọc mở rộng. Mã thông báo thông thường yêu cầu --read-write.

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ế độ phát triển)

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

Hoàn toàn linh hoạt không có rào cản — quyền đọc-ghi và khả năng chuyển đổi 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. Sẽ không giữ khóa tệp, do đó thuận tiện khi sử dụng cùng với một 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 cách sử dụng s3://bucket/path.duckdb — xem Biến môi trường để biết xác thực S3. Nếu bạn đang cân nhắc quyền 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 để được hướng dẫn triển khai và Khắc phục sự cố nếu bạn gặp vấn đề.

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

Máy khách	Vị trí cấu hình	Cài đặt một lần nhấp
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 các lệnh CLI bên dưới	-
Codex CLI	Sử dụng các lệnh CLI bên dưới hoặc ~/.codex/config.toml	-
Gemini CLI	Sử dụng các 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 → "Tùy chọn: Mở Cài đặt Người dùng (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 cho bên thứ ba quyền truy cập vào máy chủ MCP tự lưu trữ, chỉ chế độ chỉ đọc 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 hoạt động nhạy cảm tiềm ẩn khác.

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

Tự lưu trữ MCP MotherDuck: Fork repo 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 đọc mở rộng và kích hoạt chế độ SaaS để hạn chế truy cập tệp cục bộ.

Tự lưu trữ MCP DuckDB: 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 HTTP có thể truyền trực tuyến 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 môi trường 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 nó)
• 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 MCP MotherDuck
• Đóng vòng lặp: Đường ống dữ liệu nhanh hơn với MCP, DuckDB & AI (Blog)
• Đường ống dữ liệu nhanh hơn với MCP và 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 theo định dạng MAJOR.MINOR.PATCH
3. Quy trình làm việc sẽ tăng phiên bản, xuất bản lên PyPI/sổ đă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