motherduckdb/mcp-server-motherduck

DuckDB / MotherDuck 로컬 MCP 서버 – 빠른 개요

무엇인가요 – AI 어시스턴트 도구(Claude, Gemini, Cursor 등)에서 사용하는 MCP(Model-Chat-Protocol)를 지원하는 작고 자체 호스팅 가능한 서버입니다. 빠르고 임베디드 가능한 분석용 SQL 엔진인 DuckDB를 래핑하여 다음 대상에서 SQL 쿼리를 실행할 수 있게 합니다:

로컬 DuckDB 파일,
메모리 내 DuckDB 인스턴스(개발용으로 이상적),
S3에 저장된 DuckDB 파일, 또는
MotherDuck 클라우드 데이터베이스(md:).

AI에 중요한 이유 – 현대의 AI 어시스턴트는 질문에 답하거나 코드를 작성하기 위해 최신 데이터가 필요합니다. MCP를 통해 DuckDB를 노출하면 어시스턴트는 일반적인 SQL(SELECT …)을 실행하고 JSON 형식의 결과를 받을 수 있으며, 채팅 UI를 벗어나지 않고도 가능합니다.

핵심 기능 (README에 설명됨)

기능	세부 사항
SQL 엔진	DuckDB의 분석용 SQL 구문을 사용; 읽기/쓰기 쿼리 지원.
다양한 백엔드	로컬 파일, 메모리 내, S3 호스팅 DuckDB, 또는 MotherDuck(`md:`).
MCP 호환성	MCP 사양을 구현한 모든 클라이언트(Claude Desktop/Code, Gemini, Cursor, Codex, Kiro 등)와 작동 가능.
전송 옵션	`stdio`(기본값, CLI 기반 클라이언트용) 또는 HTTP(`--transport http`).
동적 DB 전환	`--allow-switch-databases`를 사용하면 런타임 중 백엔드 DB를 변경할 수 있음.
보안 제어	읽기 전용 모드, 선택적 토큰 기반 MotherDuck 인증, SaaS 모드 플래그, `--init-sql`을 통한 DuckDB 수준 강화.
Docker 준비	공식 Dockerfile 제공; 포트 8000에서 실행, 인증 정보는 환경 변수로 지원.
도구 기능	내장된 JSON 반환 도구: `execute_query`, `list_databases`, `list_tables`, `list_columns`, `switch_database_connection`.
제한 사항	기본 제한: 응답당 1,024행 / 50,000자 (사용자 정의 가능).

일반적인 사용 사례 흐름

설치 uv (Python 패키지 매니저) – pip install uv.
서버 시작 단일 명령어로 시작, 예시:
```
uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
```
이 명령어는 어시스턴트가 읽고 쓸 수 있는 메모리 내 DuckDB를 시작합니다.
AI 클라이언트 설정 – README에 나와 있는 JSON 스니펫을 클라이언트의 MCP 설정에 추가합니다. 클라이언트는 stdio 또는 HTTP를 통해 서버와 통신합니다.
쿼리 실행 – 어시스턴트가 execute_query 도구를 호출하고 JSON 형식의 행을 수신하며, 데이터를 반복, 조인, 시각화할 수 있습니다.
생산 환경 – 외부 사용자를 위한 경우, README는 MotherDuck의 호스팅된 Remote MCP 사용을 권장하며, 자체 호스팅 서버는 읽기 전용 모드, 서비스 계정 토큰, DuckDB 강화를 통해 보안을 강화해야 한다고 조언합니다.

시작 방법 (단계별)

사전 요구 사항 – uv 설치.
백엔드 선택 – 메모리(:memory:), 로컬 파일(/path/to.db), S3(s3://bucket/file.duckdb), 또는 MotherDuck(md:).

실행 – 로컬 파일, 읽기 전용 예시:

uvx mcp-server-motherduck --db-path /abs/path/to.db

클라이언트에 추가 – Claude Desktop의 경우 제공된 .mcpb 번들 다운로드; Cursor의 경우 설치 버튼 클릭; VS Code의 경우 UV 설치 배지 사용.
쿼리 실행 – execute_query 도구 사용, 예: { "sql": "SELECT * FROM orders LIMIT 10" }.

보안 및 생산 환경 팁 (README에서)

읽기 전용 모드는 파일 시스템 접근을 차단하지 않습니다. 제3자 노출 시 Remote MCP를 고려하세요.
MotherDuck 서비스 계정 토큰을 읽기 스케일링과 함께 사용하고, SaaS 모드를 활성화하여 로컬 파일 접근을 제한하세요.
자체 호스팅 DuckDB의 경우, --init-sql에 DuckDB 보안 설정을 제공하세요 (DuckDB 문서 참조).
Docker 내에서 실행하고 필요한 포트만 노출하세요.

라이선스

MIT – 자유롭게 사용, 수정, 재배포 가능.

결론 – 이 리포지토리는 현대의 AI 어시스턴트가 표준 MCP 프로토콜을 통해 DuckDB(또는 MotherDuck)를 실시간 데이터 소스로 다룰 수 있도록 하는 가벼운 브리지 제공하며, IDE 및 채팅 도구에서 실시간 SQL 기반 상호작용을 가능하게 합니다.