DuckDB를 MCP를 통해 Claude/Cursor에 연결하는 방법 (DuckDB MCP 서버 설정)

이 가이드 외에도 쿼리 스트림의 모든 기능 보기 무료로 시작하기

지원

+더 보기

라이브 데이터

내보내기를 온디맨드 SQL로 바꾸기

Excel 시트

BI 및 AI 분석

Nova에 문의하여 SQL + 차트 가져오기

노바 만나기

데이터베이스 REST API

파트너당 키 1개. 자격 증명은 공유되지 않습니다.

API를 구축하세요

+더 보기

자동화

6개 이상의 플랫폼에 예약 동기화

탐색

+더 보기

API에서 SQL로

코드 없이 SQL로 API 쿼리

탐색

+더 보기

AI 데이터베이스 MCP

Claude, Cursor, ChatGPT 및 Grok은 여러분의 데이터와 소통합니다.

Connect AI

Query Streams는 안전한 실시간 데이터 통합 플랫폼으로, 방화벽 변경 없이 단일 MCP 키를 통해 계정에 있는 모든 데이터베이스와 SaaS API를 Claude, Cursor, ChatGPT 및 Grok에 통합합니다. 이 가이드는 DuckDB MCP 커넥터를 설정하는 방법을 자세히 설명합니다. 이 커넥터를 사용하면 AI 도구가 DuckDB CLI에서 CSV 내보내기 파일을 복사하거나 직접 입력하지 않고도 이벤트, 사용자, 거래, 일별 집계, 코호트 유지율, S3의 parquet/CSV/JSON 파일 등 내장된 분석 데이터에 대한 일반적인 질문에 답할 수 있습니다. read_parquet() 노트북에서 쿼리를 실행합니다. QueryStreams.com에서 더 자세히 알아보세요. 그리고 무료로 가입하세요 AI 도구에 실제 DuckDB 질문을 해보세요.

Query Streams MCP가 DuckDB에 제공하는 기능은 무엇인가요?

오픈소스 환경에 있는 다른 "DuckDB MCP" 서버들은 AI 도구를 로컬 서버에 직접 연결합니다. .duckdb 파일을 사용하는 방법도 있지만, 이 방법은 AI 클라이언트의 설정 파일에 데이터베이스 경로를 추가하고, AI 도구가 해당 DuckDB 파일 하나에만 접근하도록 제한하며, AI가 실제로 무엇을 요청했는지에 대한 감사 기록을 남기지 않습니다. DuckDB용 Query Streams MCP 서버는 이러한 문제를 해결합니다. 하나의 키로 모든 커넥터(DuckDB 파일뿐 아니라 다른 모든 데이터베이스 및 API)를 연결하고, 완벽한 감사 기록을 제공하며, AI 도구는 DuckDB 파일 경로를 저장하지 않습니다.

방화벽 포트를 열지 않고 작동하는 방식

Query Streams 네트워크 에이전트는 로컬 환경이 저장된 컴퓨터에 한 번 설치됩니다. .duckdb 파일(랩톱, 온프레미스 서버 또는 소형 가상 머신)을 가져와 클라우드로 나가는 TLS 링크 하나만 연결합니다. 들어오는 트래픽은 전혀 노출되지 않으며, AI 도구는 사용자의 데이터를 볼 수 없습니다. .duckdb 파일 경로. 발신 전용 연결 작동 방식 →

Cursor 또는 Claude에게 제공하는 MCP 키는 범위가 지정됩니다.읽다 / 분석하다 / 실행하다언제든지 취소 가능하며 키별로 사용 횟수가 제한됩니다. AI 도구는 이러한 MCP 도구를 호출하여 작업을 수행합니다.

스키마 인텔리전스가 Query Streams MCP를 차별화하는 이유는 무엇일까요?

오픈소스 환경에서 대부분의 "DuckDB용 MCP" 서버는 AI 도구에 동일한 기능을 제공합니다. 정보 스키마 DuckDB는 낯선 사람에게 컬럼 이름, 데이터 유형, 어쩌면 기본 키까지 알려줍니다. LLM(로컬 라이프 매니저)은 그 정보를 추측해야 합니다. 이벤트 유형 = 7 무슨 뜻인가요? 유효 탑재량 건물 내부에 저장되는지, 아니면 이벤트.사용자_id 실제로 연결됩니다 사용자 ID (DuckDB 스키마에는 외래 키가 선언되어 있지 않은 경우가 많으며, 특히 테이블들이 여러 개 합쳐진 경우에는 더욱 그렇습니다.) read_parquet / read_csv_auto (소스). 그렇기 때문에 대부분의 LLM이 기본 스키마에 대해 처음 작성하는 SQL은 틀립니다. LLM 자체가 나쁜 것이 아니라, 올바른 쿼리를 실행하는 데 필요한 데이터가 부족하기 때문입니다.

Query Streams MCP는 우리가 흔히 말하는 추가 정보를 포함하여 동일한 스키마를 반환합니다. 스키마 인텔리전스(SI) — AI가 선별한 메타데이터는 프로파일링 쿼리를 실행하여 생성됩니다. 실제 AI 클라이언트가 요청하기 전에 DuckDB 데이터가 준비됩니다. 커넥터와 데이터베이스에서 SI가 활성화되면 AI가 호출하는 모든 스키마 도구가 준비됩니다.qs_get_connector_schema, qs_get_table_schema, qs_profile_table, qs_get_relationships이 함수는 기본 스키마와 함께 JSON/STRUCT 형태 힌트 및 DuckDB의 컬럼형 I/O를 위한 컬럼 프로젝션 가이드 등 6단계의 선별된 정보를 반환합니다. LLM은 더 이상 추측하지 않습니다.

이를 구체적으로 설명하기 위해, AI 클라이언트가 단일 요청으로부터 받는 응답은 다음과 같습니다. qs_get_table_schema 일반적인 DuckDB 내장 분석 데이터 웨어하우스에 대한 호출(이벤트, 사용자, 업무, 일일 집계, 실험) — 처음에는 스키마 인텔리전스 없이, 그 다음에는 스키마 인텔리전스를 적용하여.

스키마 인텔리전스가 추가하는 6개 레이어

각 계층은 LLM이 추측할 수 있는 질문 유형을 다룹니다. 선택 사항인 SI 프로파일링 패스는 스키마를 변경하지 않고 DuckDB 데이터를 대상으로 실행되며, 스캔을 위해 에이전트는 로컬에서 실행됩니다. .duckdb 읽기 전용 모드의 파일. 스키마 인텔리전스가 제공하는 기능과 최신 상태를 유지하는 방법 →

프롬프트는 같지만 SQL 쿼리는 다릅니다.

증거는 AI 도구가 실제로 작성하는 SQL에 있습니다. 동일한 커서 세션, 동일한 Claude 모델, 동일한 프롬프트입니다. "지난 분기 동안 그룹별 및 이벤트 유형별 매출 추세를 주 단위로 보여주세요." 스키마 인텔리전스가 없으면 LLM은 추측해야 합니다. 하지만 스키마 인텔리전스를 사용하면 LLM은 첫 시도에 관용적이고 컬럼형 구조에 적합한 DuckDB SQL을 작성할 수 있습니다.

Query Streams MCP를 통해 로컬 DuckDB 파일을 실행하기

Query Streams MCP는 로컬 DuckDB 데이터베이스 파일에 연결합니다. 네트워크 에이전트가 해당 파일을 엽니다. .duckdb DuckDB의 읽기 전용 모드로 파일을 저장하고 다른 모든 커넥터와 동일한 아웃바운드 클라우드 링크 및 MCP 키를 통해 AI 클라이언트에 쿼리를 제공합니다. 별도의 데이터베이스 서버를 실행할 필요가 없습니다.

MCP가 마음에 안 드시나요? 그렇다면 Nova AI를 사용해 보세요.

JSON 설정 부분을 완전히 건너뛰세요: Nova AI는 Query Streams 웹 포털에 내장되어 있습니다. 그리고 사용자의 로컬 데이터베이스에 대해 동일한 일반적인 DuckDB 질문을 합니다. .duckdb 파일 — 동일한 에이전트, 동일한 읽기 전용 적용, 동일한 스키마 인텔리전스, MCP 연결 없음.

Nova AI를 만나보세요

전제 조건

시작하기 전에 다음 사항을 확인하세요:

1. Query Streams 무료 계정은 다음에서 이용 가능합니다. my.querystreams.com.
2. 로컬 환경이 저장된 컴퓨터에 Query Streams 네트워크 에이전트가 설치됩니다. .duckdb 파일(랩톱, 서버 또는 소형 가상 머신) — 참조 쿼리 스트림 에이전트를 다운로드하세요.
3. 에이전트에 대해 구성된 DuckDB 커넥터 — 기존 커넥터를 참조하세요. 커넥터 설정 가이드 .duckdb 파일 경로. 에이전트가 경로를 보유하며, AI 도구는 절대 경로를 건드리지 않습니다.
4. MCP를 지원하는 모든 AI 클라이언트. 이 가이드에서는 Cursor, Claude Desktop, ChatGPT 및 Grok을 예로 들겠습니다. Windsurf, Zed, Continue, Cline, VS Code Copilot, Codex 또는 Goose를 사용하는 경우에도 설정 블록은 기본적으로 동일합니다.
5. 5분.

1단계: 쿼리 스트림에서 MCP 키 생성

Query Streams에 로그인하고 엽니다. MCP 페이지 (또는 먼저 로그인하세요) my.querystreams.com 클릭하고 클릭하세요 MCP (왼쪽 탐색 메뉴에서) 클릭하세요. 키를 생성합니다열쇠에 알아보기 쉬운 이름을 지정하세요 (예: 커서-랩톱 또는 클로드-데스크탑그리고 이 키에 적용할 범위를 선택하세요.

• 읽다 — AI는 커넥터를 탐색하고 스키마를 읽을 수 있습니다. 이는 다른 모든 기능에 필수적입니다.
• 분석하다 — AI는 테이블 프로파일링을 통해 테이블 간의 관계(샘플 값, 분포, 의미 유형, STRUCT/LIST 형태 힌트)를 파악할 수 있습니다. 선택 사항이지만 DuckDB 작업 시에는 강력히 권장됩니다. 중첩된 데이터의 형태와 열거형 열의 카디널리티를 이해하는 것이 LLM이 열 기반 분석 SQL을 처음부터 정확하게 작성하는 데 필수적이기 때문입니다.
• 실행하다 — 해당 AI는 실제로 SQL을 실행할 수 있습니다. 이것이 없으면 AI는 스키마 메타데이터에 대해서만 읽기 전용으로 작동합니다.

일반적인 "Claude가 내 DuckDB 데이터를 분석하도록 허용" 워크플로에서는 세 가지 범위 모두 적합합니다. 팀원이나 신뢰도가 낮은 고객에게 키를 제공하는 경우에는 범위를 줄이세요. 실행하다 그리고 검색만 허용하도록 설정하세요. 같은 페이지에서 언제든지 키를 취소할 수 있으며, AI 클라이언트는 이를 확인할 수 있습니다. MCP_KEY_REVOKED 다음 호출 시 즉시 작동을 멈춥니다. 전파 지연이 없습니다.

지금 키를 복사하세요. Query Streams는 키를 한 번만 표시하고 해시값만 저장합니다. 키를 분실하면 새 키를 생성해야 합니다. 키는 다음과 같습니다. qsmcp_ 그 뒤에 48개의 임의 문자가 오며, 이것이 AI 클라이언트가 보내는 내용입니다. X-MCP-키 요청 헤더.

2단계: AI 클라이언트에 Query Streams MCP를 추가합니다.

구성 방식은 MCP를 지원하는 모든 클라이언트에서 동일합니다. 즉, MCP 서버 항목이 다음을 가리킵니다. https://mcp.querystreams.com 열쇠를 꽂은 채로 X-MCP-키 헤더. 아래에서 클라이언트를 선택하세요.

커서 ~/.cursor/mcp.json

// ~/.cursor/mcp.json 파일을 수정하세요
{
  "mcpServers": {
    "쿼리스트림": {
      "url": "https://mcp.querystreams.com",
      "헤더": {
        "X-MCP-키": "qsmcp_여기에 키를 붙여넣으세요"
      }
    }
  }
}

클로드 데스크톱 클로드_데스크탑_설정.json

// 설정 → 개발자 → 구성 편집
{
  "mcpServers": {
    "쿼리스트림": {
      "url": "https://mcp.querystreams.com",
      "헤더": {
        "X-MCP-키": "qsmcp_여기에 키를 붙여넣으세요"
      }
    }
  }
}

챗GPT 앱 및 커넥터

// 설정 → 앱 및 커넥터 → MCP 추가
서버 URL  https://mcp.querystreams.com
인증 헤더 X-MCP-키
헤더 값 qsmcp_여기에 키를 붙여넣으세요

// ChatGPT 유료 플랜이 필요합니다
// (플러스/프로/팀/엔터프라이즈).

그록 원격 MCP 도구

// Grok → 설정 → 도구
{
  "mcp_servers": [{
    "이름": "쿼리스트림",
    "url": "https://mcp.querystreams.com",
    "인증 헤더": "X-MCP-키",
    "인증 값": "qsmcp_..."
  }]
}

AI 클라이언트를 다시 시작하세요. 다음 실행 시 위에 나열된 8개의 Query Streams MCP 도구를 감지하여 도구 팔레트에 표시합니다. Cursor 및 Claude Desktop에서는 다음 명령어를 입력하여 확인할 수 있습니다. "연결자 목록" — AI가 전화해야 합니다 qs_list_connectors 설정한 내용과 함께 DuckDB 커넥터를 반환하십시오.

3단계: AI에게 DuckDB 관련 질문을 하세요

SQL 쿼리는 직접 작성할 필요가 없습니다. AI가 알아서 처리합니다. 질문을 하면 AI가 적절한 MCP 도구를 선택하고, 에이전트가 DuckDB 데이터베이스에 대해 쿼리를 실행하면 텍스트와 표 형식으로 답변이 반환됩니다. 먼저 다음 세 가지 예시 질문을 시도해 보세요.

AI가 처음으로 도구를 호출할 때 클라이언트 측에 도구 호출 승인을 요청하는 확인 메시지가 표시될 수 있습니다. 이는 MCP의 표준 동의 절차이며, Query Streams에서 추가하는 기능은 아닙니다. 한 번 승인하면 AI는 나머지 대화를 자유롭게 진행합니다. 클라이언트 설정에서 언제든지 동의 여부를 다시 확인할 수 있습니다.

자주 묻는 질문

시작하기

관련 가이드: 쿼리 스트림 에이전트를 다운로드하세요 | 데이터베이스 커넥터 설정 | 모든 MCP 서버 가이드 | Nova AI 텍스트를 SQL로 변환

분류: MCP 서버

태그: mcp, claude, 커서, duckdb, 분석 데이터베이스, 개발자 도구, 임베디드 분석, 컬럼형 데이터베이스, parquet

메타 설명: Query Streams MCP를 통해 로컬 DuckDB 파일을 Claude 또는 Cursor에 연결합니다. 분석 중심의 기능으로 5분 만에 설정이 완료됩니다.