MotherDuck MCP 서버

Claude에 SQL 분석 기능을 제공하는 MotherDuck과 로컬 DuckDB를 통합하는 MCP 서버 구현입니다.

특징

• 하이브리드 실행 : 클라우드 기반 MotherDuck과 로컬 DuckDB 모두에서 데이터 쿼리
• 클라우드 스토리지 통합 : MotherDuck의 통합을 통해 Amazon S3 또는 기타 클라우드 스토리지에 저장된 데이터에 액세스하세요.
• 데이터 공유 : 데이터베이스 생성 및 공유
• SQL 분석 : DuckDB의 SQL 방언을 사용하여 Claude에서 직접 모든 크기의 데이터를 쿼리합니다.
• 서버리스 아키텍처 : 인스턴스나 클러스터를 구성하지 않고도 분석을 실행합니다.

구성 요소

프롬프트

서버는 하나의 프롬프트를 제공합니다.

• duckdb-motherduck-initial-prompt : DuckDB 또는 MotherDuck에 대한 연결을 초기화하고 작업을 시작하기 위한 프롬프트입니다.

도구

서버는 하나의 도구를 제공합니다.

• query : MotherDuck/DuckDB 데이터베이스에 대한 SQL 쿼리를 실행합니다.
  • 입력 :
    • query (문자열, 필수): 실행할 SQL 쿼리

DuckDB와 MotherDuck과의 모든 상호작용은 SQL 쿼리 작성을 통해 이루어집니다.

시작하기

필수 조건

• MotherDuck 계정( motherduck.com 에서 가입)
• MotherDuck 액세스 토큰
• uv 설치되어 있으면 pip install uv 또는 brew install uv 사용하여 설치할 수 있습니다.

Claude Desktop과 함께 MotherDuck MCP를 사용하려면 Claude Desktop도 설치해야 합니다.

MotherDuck 토큰 설정

1. MotherDuck 계정 에 가입하세요
2. MotherDuck UI를 통해 액세스 토큰 생성
3. 구성에 사용하기 위해 토큰을 안전하게 저장하세요

Claude Desktop과 함께 사용

1. 아직 설치하지 않았다면 claude.ai/download 에서 Claude Desktop을 설치하세요.
2. Claude Desktop 구성 파일을 엽니다.

• 빠르게 액세스하거나 처음으로 만들려면 Claude Desktop 앱을 열고 설정을 선택한 다음 "개발자" 탭을 클릭하고 마지막으로 "구성 편집" 버튼을 클릭하세요.
• claude_desktop_config.json 에 다음 구성을 추가하세요.

지엑스피1

중요 참고 사항 :

• YOUR_MOTHERDUCK_TOKEN_HERE 실제 MotherDuck 토큰으로 바꾸세요.
• YOUR_HOME_FOLDER_PATH DuckDB가 파일 작업에 사용하는 홈 디렉터리 경로로 바꾸세요. 예를 들어 macOS에서는 /Users/your_username 과 같이 입력합니다.
• DuckDB가 제대로 작동하려면 HOME 환경 변수가 필요합니다.

예제 쿼리

구성이 완료되면 Claude에게 다음과 같은 쿼리를 실행하도록 요청할 수 있습니다.

• "MotherDuck에서 새 데이터베이스와 테이블을 만듭니다"
• "내 로컬 CSV 파일에서 데이터 쿼리"
• "내 로컬 DuckDB 데이터베이스의 데이터를 MotherDuck의 테이블과 결합합니다"
• "Amazon S3에 저장된 데이터 분석"

테스트

이 서버는 Claude Desktop 및 Cursor와 같은 도구를 사용하여 실행되도록 설계되었지만, 테스트 목적으로 수동으로 시작할 수 있습니다. 서버를 수동으로 테스트할 때는 --db-path 매개변수를 사용하여 연결할 데이터베이스를 지정할 수 있습니다.

1. 기본 MotherDuck 데이터베이스 :
   • 기본 MotherDuck 데이터베이스에 연결하려면 --motherduck-token 매개변수를 사용하여 인증 토큰을 전달해야 합니다.
   uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>
2. 특정 MotherDuck 데이터베이스 :
   uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
3. 로컬 DuckDB 데이터베이스 :
   uvx mcp-server-motherduck --db-path /path/to/your/local.db
4. 메모리 내 데이터베이스 :
   uvx mcp-server-motherduck --db-path :memory:

데이터베이스 경로를 지정하지 않고 motherduck_token 환경 변수를 설정한 경우, 서버는 자동으로 기본 MotherDuck 데이터베이스( md: )에 연결됩니다.

SSE 모드에서 실행

다음 명령을 실행하여 supergateway 사용하여 SSE 모드로 서버를 실행할 수도 있습니다.

그리고 Claude Desktop, Cursor와 같은 클라이언트를 이 엔드포인트로 가리킬 수 있습니다.

문제 해결

• 연결 문제가 발생하면 MotherDuck 토큰이 올바른지 확인하세요.
• 로컬 파일 액세스 문제의 경우 --home-dir 매개변수가 올바르게 설정되었는지 확인하세요.
• PATH에서 uvx 명령을 사용할 수 있는지 확인하세요.
• spawn uvx ENOENT 오류가 발생하면 uvx 에 대한 전체 경로( which uvx 의 출력)를 지정해 보세요.
• 이전 버전 v0.4.0에서는 환경 변수를 사용했지만 이제는 매개변수를 사용합니다.

특허

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 조건에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.