mcp-server-duckdb

DuckDB용 모델 컨텍스트 프로토콜(MCP) 서버 구현으로, MCP 도구를 통해 데이터베이스 상호작용 기능을 제공합니다. LLM에서 이를 분석해 보는 것도 흥미로울 것입니다. DuckDB는 로컬 분석에 적합합니다.

개요

이 서버는 모델 컨텍스트 프로토콜을 통해 DuckDB 데이터베이스와 상호 작용하여 쿼리, 테이블 생성, 스키마 검사와 같은 데이터베이스 작업이 가능합니다.

구성 요소

자원

현재는 사용자 정의 리소스가 구현되어 있지 않습니다.

프롬프트

현재 사용자 정의 프롬프트는 구현되어 있지 않습니다.

도구

서버는 다음의 데이터베이스 상호작용 도구를 구현합니다.

• 쿼리 : DuckDB 데이터베이스에서 모든 SQL 쿼리를 실행합니다.
  • 입력 : query (문자열) - 유효한 DuckDB SQL 문
  • 출력 : 텍스트 형태의 쿼리 결과(또는 CREATE/INSERT와 같은 작업의 경우 성공 메시지)

[!NOTE] 최신 LLM은 별도의 엔드포인트가 필요 없이 모든 데이터베이스 작업(SELECT, CREATE TABLE, JOIN 등)에 적합한 SQL을 생성할 수 있으므로 서버는 별도의 특수 기능이 아닌 단일 통합 query 기능을 제공합니다.

[!NOTE] 서버가 readonly 모드로 실행 중일 때는 DuckDB의 기본 읽기 전용 보호 기능이 적용됩니다. 이를 통해 언어 모델(LLM)이 쓰기 작업(CREATE, INSERT, UPDATE, DELETE)을 수행할 수 없게 되어 데이터 무결성을 유지하고 의도치 않은 변경을 방지할 수 있습니다.

구성

필수 매개변수

• db-path (문자열): DuckDB 데이터베이스 파일의 경로
  • 데이터베이스 파일과 상위 디렉토리가 존재하지 않으면 서버는 자동으로 해당 파일을 생성합니다.
  • --readonly 지정되고 데이터베이스 파일이 존재하지 않으면 서버가 오류로 시작되지 않습니다.

선택적 매개변수

• --readonly : 서버를 읽기 전용 모드로 실행합니다.
  • 설명 : 이 플래그가 설정되면 서버는 읽기 전용 모드로 작동합니다. 즉, 다음과 같은 의미가 있습니다.
    • DuckDB 데이터베이스는 read_only=True 로 열리므로 모든 쓰기 작업이 차단됩니다.
    • 지정된 데이터베이스 파일이 존재하지 않으면 생성 되지 않습니다 .
    • 보안 이점 : 언어 모델(LLM)이 쓰기 작업을 수행하지 못하도록 하여 데이터베이스가 변경되지 않도록 보장합니다.
  • 참고 : DuckDB의 읽기 전용 연결에 대한 자세한 내용은 DuckDB Python API 문서를 참조하세요.

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 DuckDB 서버를 자동으로 설치하려면:

지엑스피1

Claude 데스크톱 통합

Claude Desktop의 구성 파일에서 MCP 서버를 구성합니다.

맥OS

위치: ~/Library/Application Support/Claude/claude_desktop_config.json

윈도우

위치: %APPDATA%/Claude/claude_desktop_config.json

• 참고: ~/mcp-server-duckdb/data/data.db DuckDB 데이터베이스 파일의 실제 경로로 바꿔야 합니다.

개발

필수 조건

• uv 패키지 관리자를 사용한 Python
• DuckDB Python 패키지
• MCP 서버 종속성

디버깅

MCP 서버는 stdio 기반 통신을 사용하기 때문에 디버깅이 어려울 수 있습니다. 최상의 디버깅 환경을 위해 MCP Inspector 사용을 권장합니다.

MCP Inspector 사용

1. npm을 사용하여 검사기를 설치합니다.

2. 디버깅 인터페이스에 액세스하려면 브라우저에서 제공된 URL을 여세요.

검사관은 다음에 대한 가시성을 제공합니다.

• 요청/응답 커뮤니케이션
• 도구 실행
• 서버 상태
• 오류 메시지