Claude Agent SDK와 ClickHouse MCP 서버로 AI 에이전트 빌드하기
Claude Agent SDK와 ClickHouse MCP 서버로 AI 에이전트 빌드하기
이 가이드에서는 ClickHouse의 MCP 서버를 사용해 ClickHouse의 SQL 플레이그라운드와 상호작용할 수 있는 Claude Agent SDK AI 에이전트를 빌드하는 방법을 배워요.
출처: 문서
본문
이 가이드에서는 ClickHouse의 MCP 서버를 사용해 ClickHouse의 SQL 플레이그라운드와 상호작용할 수 있는 Claude Agent SDK AI 에이전트를 빌드하는 방법을 배워요.
예제 노트북 이 예제는 examples 리포지토리에서 노트북으로 찾아볼 수 있어요.
전제 조건 (Prerequisites)
- 시스템에 Python이 설치되어 있어야 해요.
- 시스템에
pip이 설치되어 있어야 해요. - Anthropic API 키가 있어야 해요.
다음 단계는 Python REPL 또는 스크립트를 통해 실행할 수 있어요.
1. 라이브러리 설치하기
다음 명령을 실행해 Claude Agent SDK 라이브러리를 설치하세요:
pip install -q --upgrade pip
pip install -q claude-agent-sdk
pip install -q ipywidgets
2. 자격 증명 설정하기
다음으로 Anthropic API 키를 제공해야 해요:
import os, getpass
os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Enter Anthropic API Key:")
응답:
Enter Anthropic API Key: ········
다음으로 ClickHouse SQL 플레이그라운드에 연결하는 데 필요한 자격 증명을 정의하세요:
env = {
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "demo",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true"
}
3. MCP 서버와 Claude Agent SDK 에이전트 초기화하기
이제 ClickHouse MCP 서버가 ClickHouse SQL 플레이그라운드를 가리키도록 구성하고 에이전트를 초기화한 뒤 질문을 던져 봐요:
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 블록 안의 코드는 출력을 간결하게 필터링하고 있다는 점을 유의하세요.
응답:
🤖 I'll query the ClickHouse database to find something interesting about UK property sales.
Let me first see what databases are available:
🛠️ mcp__mcp-clickhouse__list_databases {}
🤖 Great! There's a "uk" database. Let me see what tables are available:
🛠️ mcp__mcp-clickhouse__list_tables {'database': 'uk'}
🤖 Perfect! The `uk_price_paid` table has over 30 million property sales records. Let me find something interesting:
🛠️ 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"}
🤖 Here's something fascinating: **Baker Street in London** (yes, the famous Sherlock Holmes street!) has the largest price range of any street with over 100 sales - properties sold for as low as **£2,500** and as high as **£594.3 million**, a staggering difference of over £594 million!
This makes sense given Baker Street is one of London's most prestigious addresses, running through wealthy areas like Marylebone, and has had 541 recorded sales in this dataset.