MotherDuck MCP Server

DuckDB / MotherDuck 로컬 MCP 서버

AI 어시스턴트 및 IDE를 위한 SQL 분석 및 데이터 엔지니어링.

DuckDB의 강력한 분석 SQL 엔진을 사용하여 AI 어시스턴트를 데이터에 연결하세요. 로컬 DuckDB 파일, 인메모리 데이터베이스, S3 호스팅 데이터베이스 및 MotherDuck 연결을 지원합니다. SQL 읽기 및 쓰기 쿼리 실행, 데이터베이스 카탈로그 탐색, 여러 데이터베이스 연결 간 실시간 전환을 허용합니다.

완전 관리형 원격 MCP 서버를 찾고 계신가요? → MotherDuck 원격 MCP 문서로 이동

원격 vs 로컬 MCP

📝 v0.x에서 마이그레이션하시나요?

• 기본적으로 읽기 전용: 서버가 이제 기본적으로 읽기 전용 모드로 실행됩니다. 쓰기 접근을 활성화하려면 --read-write를 추가하세요. 프로덕션 보안을 참조하세요.
• 기본 데이터베이스 변경됨: --db-path 기본값이 md:에서 :memory:로 변경되었습니다. MotherDuck을 명시적으로 사용하려면 --db-path md:를 추가하세요.
• MotherDuck 읽기 전용에는 읽기 스케일링 토큰 필요: 읽기 전용 모드의 MotherDuck 연결에는 읽기 스케일링 토큰이 필요합니다. 일반 토큰에는 --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 파일에 대한 쓰기 연결과 함께 사용하기 편리합니다. s3://bucket/path.duckdb를 사용하여 S3의 원격 DuckDB 파일에도 연결할 수 있습니다 — S3 인증에 대한 환경 변수를 참조하세요. MCP에 대한 제3자 접근을 고려 중이라면 프로덕션 보안을 참조하세요.

읽기-쓰기 모드로 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	설정 → 개발자 → 설정 편집	.mcpb (MCP 번들)
Claude Code	아래 CLI 명령 사용	-
Codex CLI	아래 CLI 명령 또는 ~/.codex/config.toml 사용	-
Gemini CLI	아래 CLI 명령 또는 ~/.gemini/settings.json 사용	-
Cursor	설정 → MCP → 새 글로벌 MCP 서버 추가
VS Code	Ctrl+Shift+P → "기본 설정: 사용자 설정 열기(JSON)"
Kiro	~/.kiro/settings/mcp.json (글로벌) 또는 .kiro/settings/mcp.json (프로젝트)

모든 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를 통해 구성 가능).

프로덕션 보안

제3자에게 자체 호스팅 MCP 서버에 대한 접근 권한을 부여할 때 읽기 전용 모드만으로는 충분하지 않습니다 — 여전히 로컬 파일 시스템 접근, DuckDB 설정 변경 및 기타 잠재적으로 민감한 작업을 허용합니다.

제3자 접근이 있는 프로덕션 배포의 경우 **MotherDuck 원격 MCP**를 권장합니다 — 설정 불필요, 읽기-쓰기 가능, MotherDuck에서 호스팅.

MotherDuck MCP 자체 호스팅: 이 저장소를 포크하여 필요에 맞게 사용자 정의하세요. **서비스 계정**과 **읽기 스케일링 토큰**을 사용하고 **SaaS 모드**를 활성화하여 로컬 파일 접근을 제한하세요.

DuckDB MCP 자체 호스팅: --init-sql를 사용하여 보안 설정을 적용하세요. 사용 가능한 옵션은 DuckDB 보안 가이드를 참조하세요.

명령줄 매개변수

환경 변수

문제 해결

• spawn uvx ENOENT: uvx의 전체 경로를 지정하세요 (실행하여 찾으려면 which uvx 실행)
• 파일 잠김: --ephemeral-connections가 켜져 있는지 확인하고 (기본값: true) 읽기-쓰기 모드로 연결되어 있지 않은지 확인하세요.

리소스

• MotherDuck MCP 문서
• 루프 닫기: MCP, DuckDB 및 AI를 통한 더 빠른 데이터 파이프라인 (블로그)
• MCP 및 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. Release New Version GitHub Action을 실행합니다.
2. MAJOR.MINOR.PATCH 형식으로 버전을 입력합니다.
3. 워크플로가 버전을 올리고, PyPI/MCP 레지스트리에 게시하고, MCPB 패키지와 함께 GitHub 릴리스를 생성합니다.

라이선스

MIT 라이선스 - LICENSE 파일을 참조하세요.

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