DuckDB MCP 서버

Claude와 같은 AI 도우미가 DuckDB와 상호 작용하여 강력한 데이터 분석 기능을 제공할 수 있도록 하는 MCP(Model Context Protocol) 서버 구현입니다.

🌟 DuckDB MCP 서버란 무엇인가요?

DuckDB MCP 서버는 모델 컨텍스트 프로토콜(MCP)을 통해 AI 어시스턴트를 고성능 분석 데이터베이스인 DuckDB 에 연결합니다. 이를 통해 AI 모델은 다음과 같은 작업을 수행할 수 있습니다.

CSV, Parquet, JSON 등 다양한 소스에서 직접 데이터를 쿼리합니다.
복잡한 설정 없이 클라우드 스토리지(S3 등)에서 데이터에 액세스하세요
SQL을 사용하여 정교한 데이터 분석 수행
적절한 맥락과 이해를 바탕으로 데이터 통찰력을 생성합니다.

🚀 주요 기능

SQL 쿼리 도구 : DuckDB의 강력한 구문으로 모든 SQL 쿼리를 실행합니다.
여러 데이터 소스 : 다음에서 직접 쿼리:
- 로컬 파일(CSV, Parquet, JSON 등)
- S3 버킷 및 클라우드 스토리지
- SQLite 데이터베이스
- DuckDB에서 지원하는 다른 모든 데이터 소스
자동 연결 관리 : 자동 데이터베이스 파일 생성 및 연결 처리
스마트 자격 증명 처리 : 원활한 AWS/S3 자격 증명 관리
문서 리소스 : AI 어시스턴트를 위한 내장 DuckDB SQL 및 데이터 가져오기 참조

📋 요구 사항

파이썬 3.10+
MCP 호환 클라이언트(Claude Desktop, Cursor, Copilot이 포함된 VS Code 등)

💻 설치

pip 사용하기

지엑스피1

출처에서

git clone https://github.com/yourusername/duckdb-mcp-server.git
cd duckdb-mcp-server
pip install -e .

🔧 구성

명령줄 옵션

duckdb-mcp-server --db-path path/to/database.db [options]

필수 매개변수:

--db-path - DuckDB 데이터베이스 파일 경로(존재하지 않으면 생성됩니다)

선택적 매개변수:

--readonly - 읽기 전용 모드로 실행합니다(데이터베이스가 없으면 오류가 발생합니다)
--s3-region - AWS S3 지역(기본값: AWS_DEFAULT_REGION 환경 변수 사용)
--s3-profile - S3 자격 증명에 대한 AWS 프로필(기본값: AWS_PROFILE 또는 '기본값' 사용)
--creds-from-env - 환경 변수에서 AWS 자격 증명 사용

🔌 Claude Desktop 설정

claude.ai/download 에서 Claude Desktop을 설치하세요
Claude Desktop의 구성 파일을 편집합니다.macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
윈도우 : %APPDATA%/Claude/claude_desktop_config.json
DuckDB MCP 서버 구성 추가:

{
  "mcpServers": {
    "duckdb": {
      "command": "duckdb-mcp-server",
      "args": [
        "--db-path",
        "~/claude-duckdb/data.db"
      ]
    }
  }
}

📊 사용 예시

구성이 완료되면 AI 도우미에게 DuckDB를 사용하여 데이터를 분석하도록 요청할 수 있습니다.

"Load the sales.csv file and show me the top 5 products by revenue"

AI는 적절한 SQL을 생성하고 실행합니다.

-- Load and query the CSV data
SELECT 
    product_name,
    SUM(quantity * price) AS revenue
FROM read_csv('sales.csv')
GROUP BY product_name
ORDER BY revenue DESC
LIMIT 5;

S3 데이터 작업

S3 버킷에서 직접 데이터 쿼리:

"Analyze the daily user signups from our analytics data in S3"

AI는 S3에 쿼리를 보내기 위해 적절한 SQL을 생성합니다.

SELECT 
    date_trunc('day', signup_timestamp) AS day,
    COUNT(*) AS num_signups
FROM read_parquet('s3://my-analytics-bucket/signups/*.parquet')
GROUP BY day
ORDER BY day DESC;

🌩️ 클라우드 스토리지 인증

DuckDB MCP 서버는 다음 순서로 AWS 인증을 처리합니다.

명시적 자격 증명( --creds-from-env 활성화된 경우)
명명된 프로필 자격 증명( --s3-profile 통해)
기본 자격 증명 체인(환경, 공유 자격 증명 파일 등)

🛠️ 개발

# Clone the repository
git clone https://github.com/yourusername/duckdb-mcp-server.git
cd duckdb-mcp-server

# Set up a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

📜 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

🙏 기여하기

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

DuckDB MCP Server

Integrations