zipnavi MCP Server
Provides home renovation guidance including building info, recent deals, permit procedures, checklists, and contractor verification based on address, powered by Korean public data.
README
zipnavi — 우리집 공사·인테리어 내비게이터 (MCP 서버)
집 공사·인테리어를 앞둔 사람이 주소 하나로 건물 이력·실거래가·인허가 절차· 시공 체크리스트·업체 검증 방법까지 안내받는 MCP 서버입니다. 공공데이터(건축HUB 건축물대장, 국토부 실거래가)와 주소 검색 API를 결합해 카카오 PlayMCP(AGENTIC PLAYER 10) 환경에서 동작하도록 설계했습니다.
⚠️ 본 서버가 제공하는 정보는 공공데이터 기반 참고용이며 법적 효력이 없습니다. 계약·인허가 전 건축물대장 원부(세움터)와 관할 행정청을 확인하세요.
도구 (5종)
| 도구 | 설명 | 데이터 원천 |
|---|---|---|
zipnavi_get_building_info |
주소 → 건축물대장 요약(구조·연식·내진·주차·승강기) + 공사 관점 인사이트 | 건축HUB getBrTitleInfo |
zipnavi_get_recent_deals |
주소 → 최근 실거래가 (매매/전월세 × 아파트·연립다세대·단독다가구·오피스텔, 1~24개월) | 국토부 RTMS 8종 |
zipnavi_get_permit_guide |
공사 유형 → 신고/허가 여부·법적 근거·절차·주의사항 (9유형) | 내장 지식 |
zipnavi_renovation_checklist |
단계별 체크리스트 (계약 전/시공 전/시공 중/준공 후) | 내장 지식 |
zipnavi_check_contractor |
시공업체 검증 방법·공식 조회처·레드 플래그 | 내장 지식 |
모든 도구는 response_format: "markdown"(기본) | "json"을 지원하고,
실패 시에도 오류 대신 행동을 유도하는 한국어 안내문을 돌려줍니다.
환경 변수
| 변수 | 필수 | 설명 |
|---|---|---|
ZIPNAVI_MODE |
아니오 | mock 또는 live. 미지정 시 키 2종이 모두 있으면 live, 아니면 mock |
DATA_GO_KR_KEY |
live 시 | 공공데이터포털 서비스 키. 일반 인증키(Decoding) 값을 사용 — Encoding 키를 넣으면 이중 인코딩으로 SERVICE_KEY 오류 발생 |
KAKAO_REST_KEY |
live 시 | 카카오 로컬 API REST 키 (주소 → 법정동코드 변환) |
JUSO_CONFM_KEY |
아니오 | juso.go.kr 승인키. 있으면 카카오 실패 시 폴백 |
ZIPNAVI_PORT |
아니오 | 기본 8000 |
키는 환경 변수로만 주입합니다. 하드코딩·저장소 커밋 금지.
실행
pip install -r requirements.txt
# mock 모드 (키 불필요, 픽스처 데이터로 전 도구 동작)
ZIPNAVI_MODE=mock python -m zipnavi.server
# live 모드
DATA_GO_KR_KEY=... KAKAO_REST_KEY=... python -m zipnavi.server
기동 후:
- MCP 엔드포인트:
http://localhost:8000/mcp(streamable-http, stateless) - 헬스체크:
http://localhost:8000/health
테스트
pip install -r requirements-dev.txt
python -m pytest tests -q
- 전 테스트 네트워크 0회 (mock 픽스처 +
httpx.MockTransport) test_server_roundtrip.py가 PlayMCP 등록 검증(initialize → tools/list → tools/call)을 인메모리로 사전 재현,test_http_roundtrip.py가 실제 HTTP로 재확인
PlayMCP 제약 준수
| 제약 | 대응 |
|---|---|
| 응답 24KB 초과 시 반려 | 마크다운은 멀티바이트 안전하게 절단하고, JSON은 유효한 축약 안내 객체로 반환 |
| TextContent만 허용 | 전 도구 텍스트 반환 + structured_output=False로 structuredContent 자동 복제 차단 (roundtrip 테스트에서 타입 검증) |
도구명 ^[A-Za-z0-9_-]{1,128}$, 'kakao' 금지 |
zipnavi_* 5종 (테스트로 검증) |
| 도구 수 3~10개 | 5개 |
| Remote HTTPS 전용 | streamable-http + 리버스 프록시(TLS 종단)로 배포 |
| 평균 100ms / p99 3s | 실거래가 다개월 조회 총 데드라인 2.6s(asyncio.wait) + 동시 요청 5개 제한(Semaphore), httpx 타임아웃 2.0s(connect 1.5s), 재시도 1회 제한 |
데이터·약관 준수
fixtures/의 mock 데이터는 API 응답 스키마만 모사한 가상 데이터입니다. 카카오 로컬 API 실응답은 약관상 저장하지 않습니다(라이브 콜 즉시 소비).- 공공데이터 응답 XML은 DTD 선언을 거부하는 파서로만 해석합니다(XXE 방어).
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.
E2B
Using MCP to run code via e2b.