ClickHouse MCP との統合

MCP は、データベース、API、ツールなどのサードパーティサービスを LLM に接続するためのプロトコルです。MCP サーバーを作成することで、クライアントがサービスとどのようにやり取りできるかを定義します。Claude Desktop、ChatGPT、Cursor、Windsurf などの MCP クライアントがサーバーに接続し、LLM がサービスと対話できるようにします。MCP は急速にデファクトプロトコルになりつつあり、私たちは 2025 年の前半に ClickHouse MCP サーバーである mcp-clickhouse を公開しました。

自然言語インターフェースは、ClickHouse ユーザーがいる領域を含め、ほぼあらゆる分野で普及しつつあります。ソフトウェアエンジニア、データエンジニア、アナリティクスエンジニアなど、あらゆる人々が対象です。私たちは皆、業務の一部に自然言語やエージェント型インターフェースを取り入れ始めています。SQL に慣れているかどうかにかかわらず、データを使った作業がかつてないほど容易になりました。私たちが目の当たりにしているのは、LLM が人々のスキルを補完し拡張する手助けをしている姿です。ソフトウェアエンジニアがデータをより活用できるようになり、データエンジニアがソフトウェア領域でできることを広げています。これほど幅広いユーザーがデータを扱えるようになった時代はかつてありませんでした。

これらのユーザー、領域、インターフェースに共通しているのは、ユーザーエクスペリエンスにおけるスピードとインタラクティブ性への期待です。ユーザーは金曜の午後にクエリを投げ、帰り道においしいバインミーを買い、月曜の朝にレポートを受け取るような使い方はしていません。LLM と協調的でインタラクティブな対話を行い、数秒で応答が返ってくるリアルなやり取りを求めています。そこにサードパーティサービスを組み込むとしても、ユーザーエクスペリエンスを損なうわけにはいきません。ユーザーがこのような形でデータベースにクエリを実行したい場合、データベース側もこの応答性に対応できる必要があります。

それこそが、ClickHouse がエージェント型 AI データワークフローに最適なデータベースである理由です。ClickHouse は、ビット、バイト、ミリ秒のいずれも無駄にしない、世界最速の分析用データベースとして構築されています。LLM やエージェントの時代が到来する前から、ClickHouse は大規模な環境でインタラクティブな分析を支えることを目指してきました。エージェント型 AI に最適なデータベースになることを当初から狙っていたわけではありませんが、時には幸運な巡り合わせが起こるものです。

今後のユースケース #

人気が高まっているとはいえ、まだ初期段階であり、ツール、ワークフロー、ユースケースは急速に進化しています。従来の SQL インターフェースや BI ツールを使わず、Claude Desktop や ChatGPT のようなチャットインターフェースを使ってデータと対話し、SQL を一切書かずにインサイトや可視化を生成する人が多く見られます。また、従来のデータ領域のバックグラウンドを持たない開発者が、エンドユーザーにデータを公開するユーザー向けアプリケーションを構築し、フロントエンドの生成だけでなく、極めて高い同時実行性のためのデータ構造化やクエリ最適化までも LLM に任せているケースも見受けられます。

さらに ClickHouse はオブザーバビリティ 2.0 に最適な選択肢になりつつあり、SRE や DevOps チームが LLM を活用してトレース、メトリクス、ログを照会し、難解なクエリ構文を使わずに全文検索と分析を融合させています。

そして、私たちはその先に来るものを構想しています。LLM が既存のオブザーバビリティデータを活用して思考を深め、ユーザーが特定のエラーやトレースをプロンプトで入力しなくても、アクセス可能なデータに基づいてアーキテクチャの提案、パフォーマンス改善、バグ修正を提示できるようになるかもしれません。

近日中に、ClickHouse Cloud はデフォルトのインターフェースとしてリモート MCP サーバーを提供する予定です。これにより、追加のローカルセットアップなしで、任意の MCP クライアントからクラウドアカウントのインスタンスに直接接続できるようになります。

早期アクセスをご希望の方は、clickhouse.ai から AI 機能のウェイティングリストにご登録ください。

ClickHouse MCP エージェントの実装例 #

すぐに始められるよう、さまざまなライブラリを ClickHouse MCP サーバーと統合する方法を示す実用的なサンプルを用意しました。

これは、オープンソースの mcp-clickhouse サーバーを使って現在すぐにお試しいただけます。これが全体像の中でどのように位置づけられるかについて詳しくは、こちらの AgentHouse のデモや、エージェント向け分析 (agent-facing analytics) に関する私たちの考察をご覧ください。

5 つのサンプルはすべて ClickHouse/examples リポジトリで公開されています。すべて ClickHouse SQL Playground に対して実行されるように構成されており、以下の設定を使用します。

1env = {
2    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
3    "CLICKHOUSE_PORT": "8443",
4    "CLICKHOUSE_USER": "demo",
5    "CLICKHOUSE_PASSWORD": "",
6    "CLICKHOUSE_SECURE": "true"
7}

また、Anthropic のモデルを使用しており、ANTHROPIC_API_KEY 環境変数を通じて API キーを設定しています。

1. Agno #

まずは、エージェント構築用の軽量で高性能なライブラリである Agno (旧称 PhiData) から始めましょう。

1async with MCPTools(command="uv run --with mcp-clickhouse --python 3.13 mcp-clickhouse", env=env, timeout_seconds=60) as mcp_tools:
2    agent = Agent(
3        model=Claude(id="claude-3-5-sonnet-20240620"),
4        markdown=True, 
5        tools = [mcp_tools]
6    )
7    await agent.aprint_response("What's the most starred project in 2025?", stream=True)

Agno の API は非常にシンプルです。ローカル MCP サーバーを起動するコマンドを指定して MCPTools を初期化すると、すべてのツールが mcp_tools 変数を介して利用可能になります。その後、最後の行でエージェントを呼び出す前に、これらのツールをエージェントに渡します。

📄 Agno の完全なサンプルを見る
🧪 Agno ノートブックを試す

2. DSPy #

DSPy は、言語モデルをプログラミングするためのスタンフォード大学発のフレームワークです。

1server_parameters = StdioServerParameters(
2    command="uv",
3    args=[
4        'run',
5        '--with', 'mcp-clickhouse',
6        '--python', '3.13',
7        'mcp-clickhouse'
8    ],
9    env=env
10)
11
12dspy.configure(lm=dspy.LM("anthropic/claude-sonnet-4-20250514"))
13
14class DataAnalyst(dspy.Signature):
15    """You are a data analyst. You'll be asked questions and you need to try to answer them using the tools you have access to. """
16
17    user_request: str = dspy.InputField()
18    process_result: str = dspy.OutputField(
19        desc=(
20            "Answer to the query"
21        )
22    )
23
24async with stdio_client(server_params) as (read, write):
25    async with ClientSession(read, write) as session:
26        await session.initialize()
27        tools = await session.list_tools()
28
29        dspy_tools = []
30        for tool in tools.tools:
31            dspy_tools.append(dspy.Tool.from_mcp_tool(session, tool))
32
33        print("Tools", dspy_tools)
34
35        react = dspy.ReAct(DataAnalyst, tools=dspy_tools)
36        result = await react.acall(user_request="What's the most popular Amazon product category")
37        print(result)

こちらは少し複雑です。同様に MCP サーバーを初期化しますが、単一の文字列コマンドではなく、コマンドと引数を分けて指定する必要があります。

また DSPy では、対話ごとに Signature クラスを指定して入力フィールドと出力フィールドを定義する必要があります。次に、React クラスを使ってエージェントを初期化する際に、そのクラスを渡します。

ReAct は「Reasoning and Acting (推論と行動)」の略で、ツールを呼び出すか処理を終了するかを LLM に判断させます。ツールが必要な場合、どのツールを呼び出すかを決定し、適切な引数を提供する役割を LLM が担います。

MCP ツールをループ処理して DSPy のツールに変換する必要がある点にも注目してください。

📄 DSPy の完全なサンプルを見る
🧪 DSPy ノートブックを試す

3. LangChain #

LangChain は、LLM を活用したアプリケーションを構築するためのフレームワークです。

1server_params = StdioServerParameters(
2    command="uv", 
3    args=[
4        "run", 
5        "--with", "mcp-clickhouse",
6        "--python", "3.13", 
7        "mcp-clickhouse"
8    ],
9    env=env
10)
11
12async with stdio_client(server_params) as (read, write):
13    async with ClientSession(read, write) as session:
14        await session.initialize()
15        tools = await load_mcp_tools(session)
16        agent = create_react_agent("anthropic:claude-sonnet-4-0", tools)
17
18        handler = UltraCleanStreamHandler()        
19        async for chunk in agent.astream_events(
20            {"messages": [{"role": "user", "content": "Who's committed the most code to ClickHouse?"}]}, 
21            version="v1"
22        ):
23            handler.handle_chunk(chunk)
24
25        print("\n")

LangChain では、MCP サーバーを初期化する際に DSPy と同様のアプローチを取ります。DSPy と同じく、MCP ツールを渡して ReAct 関数を呼び出すことでエージェントを作成します。出力をより見やすく表示するために、カスタムコード (UltraCleanStreamHandler) を作成しました (実際には Claude が書きました)。

📄 LangChain の完全なサンプルを見る
🧪 LangChain ノートブックを試す

4. LlamaIndex #

LlamaIndex は、LLM アプリケーション向けのデータフレームワークです。

1mcp_client = BasicMCPClient(
2    "uv", 
3    args=[
4        "run", 
5        "--with", "mcp-clickhouse",
6        "--python", "3.13", 
7        "mcp-clickhouse"
8    ],
9    env=env
10)
11
12mcp_tool_spec = McpToolSpec(
13    client=mcp_client,
14)
15
16tools = await mcp_tool_spec.to_tool_list_async()
17
18agent_worker = FunctionCallingAgentWorker.from_tools(
19    tools=tools, 
20    llm=llm, verbose=True, max_function_calls=10
21)
22agent = AgentRunner(agent_worker)
23
24response = agent.query("What's the most popular repository?")

LlamaIndex も、おなじみの MCP サーバー初期化手法を採用しています。その後、ツールと LLM を使ってエージェントを初期化します。デフォルトの max_function_calls の値である 5 では少なすぎて質問に答えられなかったため、10 に増やしました。

📄 LlamaIndex の完全なサンプルを見る
🧪 LlamaIndex ノートブックを試す

5. PydanticAI #

PydanticAI は、生成 AI を使った本番グレードのアプリケーションをより手軽に構築できるように設計された Python エージェントフレームワークです。

1server = MCPServerStdio(  
2    'uv',
3    args=[
4        'run',
5        '--with', 'mcp-clickhouse',
6        '--python', '3.13',
7        'mcp-clickhouse'
8    ],
9    env=env
10)
11agent = Agent('anthropic:claude-sonnet-4-0', mcp_servers=[server])
12
13async with agent.run_mcp_servers():
14    result = await agent.run("Who's done the most PRs for ClickHouse?")
15    print(result.output)

Pydantic は最もシンプルな API を持っています。ここでも同様に MCP サーバーを初期化し、エージェントに渡します。その後、サーバーを非同期コンテキストマネージャーとして実行し、そのブロック内でエージェントに質問を投げることができます。

📄 PydanticAI の完全なサンプルを見る
🧪 PydanticAI ノートブックを試す

試してみる #

MCP と ClickHouse の取り組みは始まったばかりです。皆様が構築しているものや、mcp-clickhouse を使った感想をぜひお聞かせください。

サンプルを試し、素晴らしいものを作り、フィードバックをお寄せください。問題が発生した場合やアイデアがある場合は、GitHub の issue を作成するか、Slack でお話ししましょう。