pubdata-mcp
Provides a DuckDB data mart with normalized tables of Korean public data (apartment prices, weather, air quality), allowing querying via SQL and specialized tools such as price_stats and correlate.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pubdata-mcp Compare average apartment prices in Gangnam and Seocho districts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pubdata-mcp
한국 공공데이터를 수집·정규화해 DuckDB 데이터마트에 적재하고, 이를 MCP 서버로 노출한 뒤 Ollama 로컬 LLM 에이전트가 자연어 질문에 답하는 end-to-end 파이프라인입니다.
데이터 엔지니어링(수집·정규화·안전한 쿼리 서빙)과 AI 오케스트레이션(MCP + LLM 툴콜)을 하나의 프로젝트로 보여주는 백엔드 포트폴리오입니다.
아키텍처
data.go.kr ──ingest──> DuckDB 데이터마트 ──> MCP Server ──stdio──> Ollama Agent Host
(실거래가/기상/대기질) (정규화 테이블) (툴/리소스) (자연어 → 툴콜 → 답변)ingest: 커넥터 인터페이스 + 3개 커넥터 (아파트 실거래가, 일별 기상, 일별 대기질). API 키 없으면 mock 폴백
store: DuckDB 적재 및 read-only 쿼리 (지역 partition 기반 idempotent 적재)
server: MCP 서버 (
list_datasets,describe_schema,query_sql,price_stats,correlate+pubdata://catalog리소스)host: MCP 서버를 subprocess로 띄우고 Ollama 툴콜 루프로 질의에 답하는 에이전트
데이터셋
apt_trade— 아파트 매매 실거래가 (지역/월)weather— 일별 기온·강수·풍속 (지역/일)air_quality— 일별 PM10·PM2.5·오존 (지역/일)
weather와 air_quality는 (obs_date, region_code)를 공유해 correlate 툴로 크로스 도메인
상관분석이 가능합니다 (예: 풍속 vs 미세먼지 → corr ≈ -0.95, 바람이 강한 날 미세먼지가 낮음).
핵심 백엔드 포인트는 server/safe_sql.py의 read-only SQL 가드(단일문 강제, DDL/DML 차단,
LIMIT 강제)와 DuckDB read-only 커넥션 이중 방어입니다.
Related MCP server: korean-public-data-mcp
빠른 시작
# 1. 의존성 설치 (uv)
uv sync
# 2. 데이터 적재 (키 없으면 mock 데이터로 동작)
for r in 11680 11650 11440; do
uv run pubdata-ingest apt_trade --region $r --ym 202406
uv run pubdata-ingest weather --region $r --ym 202406
uv run pubdata-ingest air_quality --region $r --ym 202406
done
# 3. MCP 서버 단독 실행 (Claude Desktop / MCP Inspector에 연결 가능)
uv run pubdata-server
# 4. 에이전트로 자연어 질의 (CLI)
uv run pubdata-agent "강남구와 서초구 아파트 평균 거래가를 비교해줘"
# 5. 웹 UI (질문 + 답변 + 툴 호출 트레이스 표시) — http://localhost:8000
uv run pubdata-web웹 UI / API
pubdata-web은 FastAPI 앱을 띄웁니다.
GET /— 질문 입력 → 답변과 함께 에이전트가 호출한 MCP 툴 트레이스(인자·결과·소요시간)를 표시POST /api/ask{"question": "..."}→{answer, model, steps, elapsed_ms, trace[]}GET /api/health— 상태 및 설정된 모델
Docker
Ollama는 호스트에서 실행 중이라고 가정합니다. compose는 host networking으로 호스트의
localhost:11434 Ollama에 바로 접근합니다 (Linux 기준).
docker compose up --build
# http://localhost:8000첫 기동 시 마트가 비어 있으면 mock 데이터로 3개 지역을 자동 적재합니다.
호스트에 tool-calling 모델(ollama pull qwen2.5:7b)이 있어야 합니다.
Docker Desktop(mac/Windows)에서는 docker-compose.yml 주석의 대안 설정을 참고하세요.
실제 API 사용
.env.example를 .env로 복사하고 PUBDATA_DATA_GO_KR_KEY에 data.go.kr 서비스 키를 넣으면
mock 대신 실데이터를 수집합니다.
Claude Desktop 연결 예시
{
"mcpServers": {
"pubdata": {
"command": "uv",
"args": ["run", "pubdata-server"],
"cwd": "/home/jcyeom/dlwlr/pubdata-mcp"
}
}
}관측성 (Observability)
모든 에이전트 실행은 data/traces.jsonl에 append됩니다 (질문·모델·툴 궤적·소요시간·에러·답변).
GET /api/traces?limit=20— 최근 실행 조회 (최신순)best-effort 로깅이라 실패해도 요청에 영향 없음
평가 (Eval)
골든 케이스로 에이전트 품질을 회귀 검증합니다.
uv run pubdata-eval각 케이스는 3가지를 채점합니다:
answer-correctness: 답변에 기대값(실데이터 숫자)이 포함되는가 (콤마 무시 비교)
tool-trajectory: 기대한 MCP 툴이 호출됐는가
error-free: 툴 에러가 없었는가
결과는 표로 출력되고 data/eval_report.json에 저장됩니다. 하나라도 실패하면 exit code 1 (CI 연동 가능).
로컬 LLM 재현성을 위해 에이전트는 temperature=0으로 호출합니다.
테스트
uv run pytest # 23 tests: SQL 가드, 파이프라인, 관측성, eval 스코어링로드맵
end-to-end 파이프라인 (ingest → DuckDB → MCP → Ollama 에이전트)
read-only SQL 가드 + idempotent 적재
Docker 배포 + 웹 UI (툴 트레이스 표시)
툴콜 정확도 eval 셋 + 요청 트레이싱/관측성
기상/대기질 커넥터 추가 → 크로스 도메인 상관분석 (correlate 툴)
기상/대기질 실 API 연동 (현재 mock, apt_trade는 실 API 지원)
수집 스케줄러(APScheduler) + 증분 적재
Available Tools
5 toolscorrelateA
Pearson correlation between two numeric columns across two datasets.
Joins the tables on their shared keys (obs_date and/or region_code) and returns corr(col_a, col_b) plus the joined sample size. Example: correlate weather.avg_wind_ms with air_quality.pm10 to see whether windy days have cleaner air. Table and column names are validated against the live schema before use.
Inputs: col_a (required), col_b (required), table_a (required), table_b (required).
describe_schemaB
Return column names and types for a table so the agent can write SQL.
Inputs: table (required).
list_datasetsA
List datasets available in the mart with their title and description.
Inputs: no named parameters. Returns: result
price_statsA
Average / min / max / count of price_manwon grouped by a column.
A convenience analytics tool so the agent needn't hand-write aggregation SQL.
Inputs: table, group_by.
query_sqlA
Run a read-only SELECT against the mart.
Only single SELECT / WITH statements are allowed; results are row-capped. Use describe_schema to learn column names before querying.
Inputs: sql (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clear, distinct purpose: listing datasets, describing schemas, running SQL queries, computing price statistics, and calculating correlations. No overlap or ambiguity.
All tools use consistent snake_case naming with verb-first patterns (list_datasets, describe_schema, query_sql, price_stats, correlate). The single verb 'correlate' fits the pattern.
Five tools cover the core functionality of data discovery, schema exploration, custom queries, and common analytics. This is a well-scoped set for a data mart server.
The tool set covers essential workflows: discover (list_datasets), understand (describe_schema), query (query_sql), and two analytics helpers. Minor gaps like missing aggregation functions, but overall complete for the intended domain.
Maintenance
Related MCP Connectors
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Agent-native MCP server over 49M+ US public and government records, privacy-first, always current.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for Korean government power/energy statutory plans. Enables AI agents to search and retrieve public power plan documents.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI to query real-time Korean public data including weather, real estate prices, air quality, economic indicators, and business registration via natural language.1MIT
- FlicenseNot gradedqualityCmaintenanceKorean public-data MCP servers for AI agents, enabling natural language queries to KOSIS statistics and other Korean official data sources without requiring local accounts or API keys.-
- FlicenseNot gradedqualityDmaintenanceMCP server for querying Seoul's official air quality data, including real-time and hourly measurements by district. Enables AI assistants to answer questions about fine dust and air pollution using public data from Seoul Open Data Plaza.-