Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Claude Agent SDK와 ClickHouse MCP 서버로 AI 에이전트를 구축하는 방법

View as MarkdownEdit this pageReport an issueSet up docs MCP

이 가이드에서는 Claude Agent SDK를 사용해 ClickHouse MCP 서버를 통해 ClickHouse SQL playground와 상호작용할 수 있는 AI 에이전트를 구축하는 방법을 알아봅니다.

사전 요구 사항

  • 시스템에 Python이 설치되어 있어야 합니다.
  • 시스템에 pip가 설치되어 있어야 합니다.
  • Anthropic API Key가 필요합니다.

다음 단계는 Python REPL 또는 스크립트에서 실행할 수 있습니다.

라이브러리 설치

다음 명령을 실행하여 Claude Agent SDK 라이브러리를 설치하십시오.

pip install -q --upgrade pip
pip install -q claude-agent-sdk
pip install -q ipywidgets

자격 증명 설정

다음으로, Anthropic API Key를 입력해야 합니다.

import os, getpass
os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Enter Anthropic API Key:")
응답response
Enter Anthropic API Key: ········

다음으로, ClickHouse SQL playground에 연결하는 데 필요한 자격 증명을 정의합니다.

env = {
    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "demo",
    "CLICKHOUSE_PASSWORD": "",
    "CLICKHOUSE_SECURE": "true"
}

MCP 서버와 Claude Agent SDK 에이전트 초기화

이제 ClickHouse MCP 서버가 ClickHouse SQL playground를 가리키도록 구성한 후, 에이전트를 초기화하고 질문을 하나 해보겠습니다.

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, UserMessage, TextBlock, ToolUseBlock
options = ClaudeAgentOptions(
    allowed_tools=[
        "mcp__mcp-clickhouse__list_databases",
        "mcp__mcp-clickhouse__list_tables", 
        "mcp__mcp-clickhouse__run_select_query",
        "mcp__mcp-clickhouse__run_chdb_select_query"
    ],
    mcp_servers={
        "mcp-clickhouse": {
            "command": "uv",
            "args": [
                "run",
                "--with", "mcp-clickhouse",
                "--python", "3.10",
                "mcp-clickhouse"
            ],
            "env": env
        }
    }
)

async for message in query(prompt="Tell me something interesting about UK property sales", options=options):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(f"🤖 {block.text}")
            if isinstance(block, ToolUseBlock):
                print(f"🛠️ {block.name} {block.input}")
    elif isinstance(message, UserMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)

간결하게 보여주기 위해 for 블록 내부의 코드는 출력을 필터링합니다.

응답response
🤖 ClickHouse 데이터베이스를 쿼리하여 영국 부동산 거래와 관련된 흥미로운 내용을 찾아보겠습니다.

먼저 사용 가능한 데이터베이스를 확인하겠습니다.
🛠️ mcp__mcp-clickhouse__list_databases {}
🤖 좋습니다! "uk" 데이터베이스가 있습니다. 이제 어떤 테이블을 사용할 수 있는지 살펴보겠습니다.
🛠️ mcp__mcp-clickhouse__list_tables {'database': 'uk'}
🤖 좋습니다! `uk_price_paid` 테이블에는 3천만 건이 넘는 부동산 거래 기록이 있습니다. 흥미로운 내용을 찾아보겠습니다.
🛠️ mcp__mcp-clickhouse__run_select_query {'query': "\nSELECT \n    street,\n    town,\n    max(price) as max_price,\n    min(price) as min_price,\n    max(price) - min(price) as price_difference,\n    count() as sales_count\nFROM uk.uk_price_paid\nWHERE street != ''\nGROUP BY street, town\nHAVING sales_count > 100\nORDER BY price_difference DESC\nLIMIT 1\n"}
🤖 흥미로운 사실이 하나 있습니다. **런던의 Baker Street**(네, 그 유명한 Sherlock Holmes의 거리입니다!)는 거래 건수가 100건이 넘는 거리 가운데 가격 차이가 가장 큽니다. 최저 **£2,500**에 거래된 부동산부터 최고 **£594.3 million**에 거래된 부동산까지 있어, 그 차이가 무려 £594 million을 넘습니다!

Baker Street는 Marylebone 같은 부유한 지역을 지나는 런던의 대표적인 고급 주소지 중 하나이므로, 이런 결과도 충분히 이해할 만합니다. 또한 이 데이터셋에는 해당 거리의 거래가 541건 기록되어 있습니다.
Navigation