mcp-server-motherduck

MotherDuck의 DuckDB MCP 서버

DuckDB 및 MotherDuck 데이터베이스와 상호 작용하여 AI Assistant 및 IDE에 SQL 분석 기능을 제공하는 MCP 서버 구현입니다.

자원

특징

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

구성 요소

프롬프트

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

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

도구

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

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

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

시작하기

일반 전제 조건

uv 설치되어 있으면 pip install uv 또는 brew install uv 사용하여 설치할 수 있습니다.

Claude Desktop이나 다른 MCP 호환 클라이언트와 함께 MCP를 사용하려면 해당 클라이언트를 설치해야 합니다.

DuckDB의 필수 구성 요소

사전 요구 사항 없음. MCP 서버는 즉시 메모리 내 데이터베이스를 생성할 수 있습니다.
또는 기존 로컬 DuckDB 데이터베이스 파일이나 원격 개체 스토리지(예: AWS S3)에 저장된 파일에 연결합니다.

로컬 DuckDB에 연결을 참조하세요.

MotherDuck의 전제 조건

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

커서를 사용한 사용

아직 설치하지 않았다면 cursor.com/downloads 에서 Cursor를 설치하세요.
열린 커서:

처음으로 글로벌하게 설정하려면 설정->MCP로 가서 "+ 새로운 글로벌 MCP 서버 추가"를 클릭하세요.
이렇게 하면 다음 구성을 추가할 mcp.json 파일이 열립니다.

지엑스피1

VS Code를 사용한 사용

가장 빠른 설치를 위해 이 README의 맨 위에 있는 "UV로 설치" 버튼 중 하나를 클릭하세요.

수동 설치

VS Code의 사용자 설정(JSON) 파일에 다음 JSON 블록을 추가합니다. Ctrl + Shift + P 를 누르고 Preferences: Open User Settings (JSON) 입력하면 됩니다.

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "motherduck_token",
        "description": "MotherDuck Token",
        "password": true
      }
    ],
    "servers": {
      "motherduck": {
        "command": "uvx",
        "args": [
          "mcp-server-motherduck",
          "--db-path",
          "md:",
          "--motherduck-token",
          "${input:motherduck_token}"
        ]
      }
    }
  }
}

원하는 경우, 작업 공간의 .vscode/mcp.json 파일에 추가할 수 있습니다. 이렇게 하면 다른 사용자와 구성을 공유할 수 있습니다.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "motherduck_token",
      "description": "MotherDuck Token",
      "password": true
    }
  ],
  "servers": {
    "motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "${input:motherduck_token}"
      ]
    }
  }
}

Claude Desktop과 함께 사용

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

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

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

중요 참고 사항 :

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

MotherDuck 쿼리 시 MCP 서버 보안

MCP 서버가 제3자에게 노출되어 데이터에 대한 읽기 권한만 가져야 하는 경우 읽기 확장 토큰을 사용하고 MCP 서버를 SaaS 모드로 실행하는 것이 좋습니다.

읽기 확장 토큰은 최대 4개의 동시 읽기 복제본을 허용하여 확장 가능한 읽기 작업을 지원하는 특수 액세스 토큰으로, 여러 최종 사용자의 성능을 향상하는 동시에 쓰기 기능을 제한합니다 . 읽기 확장 토큰을 생성하는 방법은 읽기 확장 설명서 를 참조하십시오.

MotherDuck의 SaaS 모드 는 로컬 파일, 데이터베이스, 확장 프로그램 및 구성에 대한 액세스를 제한하여 보안을 강화합니다. 따라서 더 엄격한 환경 보호가 필요한 타사 도구에 적합합니다. SaaS 모드 설명서 에서 자세한 내용을 확인하세요.

보안 구성

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_READ_SCALING_TOKEN_HERE>",
        "--saas-mode"
      ]
    }
  }
}

로컬 DuckDB에 연결

로컬 DuckDB에 연결하려면 MotherDuck 토큰을 사용하는 대신 로컬 DuckDB 데이터베이스 파일의 경로를 지정하거나 메모리 내 데이터베이스의 경우 :memory: 사용하세요.

메모리 내 데이터베이스:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        ":memory:"
      ]
    }
  }
}

로컬 DuckDB 파일:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "/path/to/your/local.db"
      ]
    }
  }
}

읽기 전용 모드 의 로컬 DuckDB 파일:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "/path/to/your/local.db",
        "--read-only"
      ]
    }
  }
}

참고 : 로컬 파일 기반 DuckDB 연결의 읽기 전용 모드는 단기 연결도 사용합니다. 쿼리 MCP 도구를 사용할 때마다 임시 연결이 생성되고 쿼리가 실행되며 연결이 닫힙니다. 이 기능은 DuckDB 내에서 DBT를 사용하여 데이터를 모델링하고 MCP 클라이언트(Windsurf/Cline/Claude/Cursor)를 사용하여 데이터베이스를 탐색하는 워크플로에서 영감을 얻었습니다. 단기 연결은 각 도구를 실행한 후 연결을 해제하여 다음 도구가 연결할 수 있도록 합니다.

예제 쿼리

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

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

테스트

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

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

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

SSE 모드에서 실행

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

npx -y supergateway --stdio "uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>"

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

개발 구성

로컬 개발 환경에서 서버를 실행하려면 다음 구성을 사용하세요.

 {
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/local/mcp-server-motherduck",
        "run",
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

문제 해결

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

특허

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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

MotherDuck과 로컬 DuckDB를 위한 MCP 서버입니다.

Related Resources

Reddit Discussion about this server

Related MCP Servers

mcp-server-duckdb
ktanaka101
-
security
A
license
-
quality
A Model Context Protocol (MCP) server implementation for DuckDB, providing database interaction capabilities through MCP tools. It would be interesting to have LLM analyze it. DuckDB is suitable for local analysis.
Last updated -
5
105
Python
MIT License
Duck Duck MCP
qwang07
-
security
A
license
-
quality
This MCP server utilizes DuckDuckGo for web searches, providing structured search results with metadata and features like smart content classification and language detection, facilitating easy integration with AI clients supporting the MCP protocol.
Last updated -
1
25
1
JavaScript
MIT License
DuckDuckGo MCP Server
nickclyde
A
security
A
license
A
quality
A Model Context Protocol (MCP) server that provides web search capabilities through DuckDuckGo, with additional features for content fetching and parsing.
Last updated -
2
26
Python
MIT License
DBHub
bytebase
-
security
A
license
-
quality
Universal database MCP server connecting to MySQL, PostgreSQL, SQLite, DuckDB and etc.
Last updated -
3
548
TypeScript
MIT License

View all related MCP servers

Appeared in Searches

Guide to Accessing a Self-Hosted Appwrite Instance