Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Claude Agent SDK と ClickHouse MCPサーバーを使って AIエージェントを構築する方法

このガイドでは、Claude Agent SDK を使って AIエージェントを構築し、ClickHouse の MCPサーバー 経由で ClickHouse の SQL Playground と連携する方法を学びます。

前提条件

  • システムに Python がインストールされている必要があります。
  • システムに pip がインストールされている必要があります。
  • Anthropic APIキーが必要です。

以下の手順は、Python REPL からでもスクリプトからでも実行できます。

ライブラリをインストールする

次のコマンドを実行して、Claude Agent SDK ライブラリをインストールします。

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

認証情報を設定する

次に、Anthropic APIキーを指定する必要があります。

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
🤖 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.