> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Claude Agent SDK와 ClickHouse MCP 서버로 AI 에이전트를 구축하는 방법을 알아봅니다

이 가이드에서는 [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview)를 사용해 [ClickHouse MCP 서버](https://github.com/ClickHouse/mcp-clickhouse)를 통해
[ClickHouse SQL playground](https://sql.clickhouse.com/)와 상호작용할 수 있는 AI 에이전트를 구축하는 방법을 알아봅니다.

<Info>
  **예시 노트북**

  이 예시는 [examples 리포지토리](https://github.com/ClickHouse/examples/blob/main/ai/mcp/claude-agent/claude-agent.ipynb)의 노트북에서 확인할 수 있습니다.
</Info>

<div id="prerequisites">
  ## 사전 요구 사항
</div>

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

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

<Steps>
  <Step title="라이브러리 설치" id="install-libraries">
    다음 명령을 실행하여 Claude Agent SDK 라이브러리를 설치하십시오.

    ```python theme={null}
    pip install -q --upgrade pip
    pip install -q claude-agent-sdk
    pip install -q ipywidgets
    ```
  </Step>

  <Step title="자격 증명 설정" id="setup-credentials">
    다음으로, Anthropic API Key를 입력해야 합니다.

    ```python theme={null}
    import os, getpass
    os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Enter Anthropic API Key:")
    ```

    ```response title="응답" theme={null}
    Enter Anthropic API Key: ········
    ```

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

    ```python theme={null}
    env = {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true"
    }
    ```
  </Step>

  <Step title="MCP 서버와 Claude Agent SDK 에이전트 초기화" id="initialize-mcp-and-agent">
    이제 ClickHouse MCP 서버가 ClickHouse SQL playground를 가리키도록 구성한 후,
    에이전트를 초기화하고 질문을 하나 해보겠습니다.

    ```python theme={null}
    from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, UserMessage, TextBlock, ToolUseBlock
    ```

    ```python theme={null}
    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 title="응답" theme={null}
    🤖 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건 기록되어 있습니다.
    ```
  </Step>
</Steps>