예시 노트북이 예시는 examples 리포지토리의 노트북으로도 확인할 수 있습니다.
사전 준비 사항
- 시스템에 Python이 설치되어 있어야 합니다.
- 시스템에
pip가 설치되어 있어야 합니다. - OpenAI API Key가 필요합니다.
1
라이브러리 설치
다음 명령을 실행해 mcp-agent 라이브러리를 설치합니다:pip install -q --upgrade pip
pip install -q mcp-agent openai
pip install -q ipywidgets
2
자격 증명 설정
다음으로, OpenAI API Key를 입력해야 합니다:import os, getpass
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter OpenAI API Key:")
Response
Enter OpenAI API Key: ········
env = {
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "demo",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true"
}
3
MCP Server 및 mcp-agent 에이전트 초기화
이제 ClickHouse MCP 서버가 ClickHouse SQL 플레이그라운드를 가리키도록 구성하고, 에이전트를 초기화한 다음 질문을 입력합니다:from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
from mcp_agent.config import Settings, MCPSettings, MCPServerSettings, OpenAISettings
settings = Settings(
execution_engine="asyncio",
openai=OpenAISettings(
default_model="gpt-5-mini-2025-08-07",
),
mcp=MCPSettings(
servers={
"clickhouse": MCPServerSettings(
command='uv',
args=[
"run",
"--with", "mcp-clickhouse",
"--python", "3.10",
"mcp-clickhouse"
],
env=env
),
}
),
)
app = MCPApp(name="mcp_basic_agent", settings=settings)
async with app.run() as mcp_agent_app:
logger = mcp_agent_app.logger
data_agent = Agent(
name="database-anayst",
instruction="""You can answer questions with help from a ClickHouse database.""",
server_names=["clickhouse"],
)
async with data_agent:
llm = await data_agent.attach_llm(OpenAIAugmentedLLM)
result = await llm.generate_str(
message="Tell me about UK property prices in 2025. Use ClickHouse to work it out."
)
logger.info(result)
Response
[10/10/25 11:26:20] INFO Starting MCP server 'mcp-clickhouse' with transport 'stdio' server.py:1502
2025-10-10 11:26:20,183 - mcp.server.lowlevel.server - INFO - Processing request of type ListToolsRequest
2025-10-10 11:26:20,184 - mcp.server.lowlevel.server - INFO - Processing request of type ListPromptsRequest
2025-10-10 11:26:20,185 - mcp.server.lowlevel.server - INFO - Processing request of type ListResourcesRequest
[INFO] 2025-10-10T11:26:20 mcp_agent.workflows.llm.augmented_llm_openai.database-anayst - Using reasoning model 'gpt-5-mini-2025-08-07' with
'medium' reasoning effort
[INFO] 2025-10-10T11:26:23 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
{
"data": {
"progress_action": "Calling Tool",
"tool_name": "list_databases",
"server_name": "clickhouse",
"agent_name": "database-anayst"
}
}
2025-10-10 11:26:23,477 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
2025-10-10 11:26:23,479 - mcp-clickhouse - INFO - Listing all databases
2025-10-10 11:26:23,479 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:24,375 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
2025-10-10 11:26:24,551 - mcp-clickhouse - INFO - Found 38 databases
[INFO] 2025-10-10T11:26:26 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
{
"data": {
"progress_action": "Calling Tool",
"tool_name": "list_tables",
"server_name": "clickhouse",
"agent_name": "database-anayst"
}
}
2025-10-10 11:26:26,825 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
2025-10-10 11:26:26,832 - mcp-clickhouse - INFO - Listing tables in database 'uk'
2025-10-10 11:26:26,832 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:27,311 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
2025-10-10 11:26:28,738 - mcp-clickhouse - INFO - Found 9 tables
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
{
"data": {
"progress_action": "Calling Tool",
"tool_name": "run_select_query",
"server_name": "clickhouse",
"agent_name": "database-anayst"
}
}
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
{
"data": {
"progress_action": "Calling Tool",
"tool_name": "run_select_query",
"server_name": "clickhouse",
"agent_name": "database-anayst"
}
}
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
{
"data": {
"progress_action": "Calling Tool",
"tool_name": "run_select_query",
"server_name": "clickhouse",
"agent_name": "database-anayst"
}
}
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
{
"data": {
"progress_action": "Calling Tool",
"tool_name": "run_select_query",
"server_name": "clickhouse",
"agent_name": "database-anayst"
}
}
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
{
"data": {
"progress_action": "Calling Tool",
"tool_name": "run_select_query",
"server_name": "clickhouse",
"agent_name": "database-anayst"
}
}
2025-10-10 11:26:48,366 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
2025-10-10 11:26:48,367 - mcp-clickhouse - INFO - Executing SELECT query: SELECT
count(*) AS transactions,
avg(price) AS avg_price,
quantileExact(0.5)(price) AS median_price,
min(price) AS min_price,
max(price) AS max_price
FROM uk.uk_price_paid_simple_partitioned
WHERE toYear(date)=2025
2025-10-10 11:26:48,367 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:49,262 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
2025-10-10 11:26:49,407 - mcp-clickhouse - INFO - Query returned 1 rows
2025-10-10 11:26:49,408 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
2025-10-10 11:26:49,408 - mcp-clickhouse - INFO - Executing SELECT query: SELECT toMonth(date) AS month, count(*) AS transactions, avg(price) AS avg_price, quantileExact(0.5)(price) AS median_price
FROM uk.uk_price_paid_simple_partitioned
WHERE toYear(date)=2025
GROUP BY month
ORDER BY month
2025-10-10 11:26:49,408 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:49,857 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
2025-10-10 11:26:50,067 - mcp-clickhouse - INFO - Query returned 8 rows
2025-10-10 11:26:50,068 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
2025-10-10 11:26:50,069 - mcp-clickhouse - INFO - Executing SELECT query: SELECT town, count(*) AS transactions, avg(price) AS avg_price
FROM uk.uk_price_paid_simple_partitioned
WHERE toYear(date)=2025
GROUP BY town
HAVING transactions >= 50
ORDER BY avg_price DESC
LIMIT 10
2025-10-10 11:26:50,069 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:50,594 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
2025-10-10 11:26:50,741 - mcp-clickhouse - INFO - Query returned 10 rows
2025-10-10 11:26:50,744 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
2025-10-10 11:26:50,746 - mcp-clickhouse - INFO - Executing SELECT query: SELECT toYear(date) AS year, count(*) AS transactions, avg(price) AS avg_price, quantileExact(0.5)(price) AS median_price
FROM uk.uk_price_paid_simple_partitioned
WHERE toYear(date) IN (2024,2025)
GROUP BY year
ORDER BY year
2025-10-10 11:26:50,747 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:51,256 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
2025-10-10 11:26:51,447 - mcp-clickhouse - INFO - Query returned 2 rows
2025-10-10 11:26:51,449 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
2025-10-10 11:26:51,452 - mcp-clickhouse - INFO - Executing SELECT query: SELECT type, count(*) AS transactions, avg(price) AS avg_price, quantileExact(0.5)(price) AS median_price
FROM uk.uk_price_paid
WHERE toYear(date)=2025
GROUP BY type
ORDER BY avg_price DESC
2025-10-10 11:26:51,452 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:51,952 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
2025-10-10 11:26:52,166 - mcp-clickhouse - INFO - Query returned 5 rows
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp_basic_agent - Summary (TL;DR)
- Based on the UK Price Paid tables in ClickHouse, for transactions recorded in 2025 so far there are 376,633 sales with an average price of
£362,283 and a median price of £281,000. The data appears to include only months Jan–Aug 2025 (so 2025 is incomplete). There are extreme
outliers (min £100, max £127,700,000) that skew the mean.
계산한 내용 (방법)
ClickHouse의 uk.price-paid 테이블에서 집계를 실행했습니다:
- uk.uk_price_paid_simple_partitioned에서 2025년 전체 요약 (건수, 평균, 중앙값, 최솟값, 최댓값)
- 2025년 월별 분석 (거래 건수, 평균, 중앙값)
- 2025년 평균 가격 기준 상위 도시 (거래 건수 >= 50인 도시)
- 연도 비교: 2024년 vs 2025년 (건수, 평균, 중앙값)
- uk.uk_price_paid를 사용한 2025년 부동산 유형별 분석 (건수, 평균, 중앙값)
주요 수치 (데이터셋 기준)
- 2025년 전체 (기록된 거래): 거래 건수 = 376,633; 평균 가격 = £362,282.66; 중앙값 = £281,000; 최솟값 = £100; 최댓값 =
£127,700,000.
- 월별 (2025년): (월, 거래 건수, 평균 가격, 중앙값)
- 1월: 53,927건, 평균 £386,053, 중앙값 £285,000
- 2월: 58,740건, 평균 £371,803, 중앙값 £285,000
- 3월: 95,274건, 평균 £377,200, 중앙값 £315,000
- 4월: 24,987건, 평균 £331,692, 중앙값 £235,000
- 5월: 39,013건, 평균 £342,380, 중앙값 £255,000
- 6월: 41,446건, 평균 £334,667, 중앙값 £268,500
- 7월: 44,431건, 평균 £348,293, 중앙값 £277,500
- 8월: 18,815건, 평균 £364,653, 중앙값 £292,999
(데이터셋에는 1~8월 데이터만 포함되어 있습니다.)
- 평균 가격 기준 상위 도시 (2025년, 거래 건수 ≥50인 도시)
- TRING: 126건, 평균 £1,973,274
- BUCKHURST HILL: 98건, 평균 £1,441,331
- ASCOT: 175건, 평균 £1,300,748
- RADLETT: 69건, 평균 £1,160,217
- COBHAM: 115건, 평균 £1,035,192
- EAST MOLESEY, BEACONSFIELD, ESHER, CHALFONT ST GILES, THAMES DITTON도 상위 10위에 포함됩니다 (모두 평균 가격이 높은 통근자/부유층 도시).
- 연도 비교 (기록 기준 2024년 vs 2025년)
- 2024년: 859,960건, 평균 £390,879, 중앙값 £280,000
- 2025년: 376,633건, 평균 £362,283, 중앙값 £281,000
(2025년 건수가 훨씬 적은 이유는 데이터셋이 연도의 일부만 포함하기 때문입니다.)
- 부동산 유형별 (2025년)
- 단독주택(detached): 85,362건, 평균 £495,714, 중앙값 £415,000
- 반단독주택(semi-detached): 107,580건, 평균 £319,922, 중앙값 £270,000
- 아파트(flat): 62,975건, 평균 £298,529, 중앙값 £227,000
- 연립주택(terraced): 112,832건, 평균 £286,616, 중앙값 £227,000
- 기타(other): 7,884건, 평균 £1,087,765 (중앙값 £315,000) — 소규모 그룹 및 이상값 효과 주의
중요한 주의사항 및 데이터 품질 참고사항
- 데이터셋은 2025년에 대해 부분적으로만 존재합니다 (1~8월만 포함). "2025년" 합계는 연간 전체 수치가 아닙니다.
- 큰 이상값이 존재합니다 (예: 최댓값 £127.7M, 최솟값 £100). 이는 데이터 입력 오류 또는 비표준 기록을 포함할 가능성이 있으며 평균을 왜곡합니다. 여기서는 중앙값이 더 견고한 지표입니다.
- "기타" 부동산 유형의 평균은 건수가 적고 이질적이며 이상값으로 인해 불안정합니다.
- is_new, duration 또는 기타 메타데이터로 필터링하지 않았습니다. 해당 필터를 적용하면 결과가 달라질 수 있습니다 (예: 신축 건물 또는 임차권 제외).
- 테이블은 Price Paid 방식의 거래 기록(기록된 매매)입니다 — 호가나 감정가를 직접 나타내지 않습니다.
다음 단계 제안 (실행 가능)
- 명백한 이상값 제거 (예: £10k 미만 또는 £10M 초과 가격) 후 평균/중앙값 재계산.
- 지역 / 카운티 / 우편번호 구역별 요약 및 지도 생성.
- 2025년 추세를 보여주기 위한 전월 대비 또는 3개월 이동 중앙값 계산.
- 월별 전년 대비(YoY) 성장률 산출 (예: 2025년 3월 vs 2024년 3월).
- 단순 외삽 또는 시계열 모델링을 사용한 2025년 전체 예측 (단, 누락된 월/이상값 처리 방법 결정 후 진행하는 것이 좋습니다).
원하신다면:
- 극단적인 이상값 제거 후 동일한 집계를 재실행하여 정제된 결과를 보여드릴 수 있습니다.
- YoY 월별 성장률 및 차트 생성 (차트로 활용 가능한 CSV 또는 JSON 집계 반환 가능).
다음으로 무엇을 원하시나요?
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_aggregator.database-anayst - Last aggregator closing, shutting down all persistent
connections...
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_connection_manager - Disconnecting all persistent server connections...
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_connection_manager - clickhouse: Requesting shutdown...
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_connection_manager - All persistent server connections signaled to disconnect.
[INFO] 2025-10-10T11:27:52 mcp_agent.mcp.mcp_aggregator.database-anayst - Connection manager successfully closed and removed from context
[INFO] 2025-10-10T11:27:52 mcp_agent.mcp_basic_agent - MCPApp cleanup
{
"data": {
"progress_action": "Finished",
"target": "mcp_basic_agent",
"agent_name": "mcp_application_loop"
}
}