만든 것

"도쿄도 시부야구의 최근 맨션 거래 가격을 알려주세요"라고 물으면, 국토교통성(MLIT)의 실제 데이터를 바탕으로 건수·중앙값·평균값·가격대 분포·지역별 중앙값까지 정리해서 답변해 주는 MCP 서버를 만들었습니다.

"japan-realestate-mcp 연동을 사용했습니다"라는 표시가 나타나며, MCP 서버가 호출되고 있음을 알 수 있습니다. 시부야구 중고 맨션 1,298건분의 데이터를 집계하여 중앙값·평균값·가격대 분포·에리어별 중앙값까지 반환합니다. 이것은 모두 국토교통성의 실제 거래 데이터입니다.

사용 가능한 도구는 4개입니다.

GitHub와 Smithery에서 공개하고 있습니다.

• GitHub: https://github.com/kakarsatoshi-bot/japan-realestate-mcp
• Smithery: https://smithery.ai/servers/kakar-satoshi/japan-realestate-mcp

만든 이유

부동산 시세는 AI가 대답할 수 없었던 영역

"시부야구의 맨션 시세는 얼마인가요?"라는 질문은 ChatGPT나 Claude에게 물어도 학습 데이터 시점의 오래된 정보만 돌아옵니다. 부동산 가격은 매년 변동하기 때문에 실시간 데이터가 필수적입니다.

국토교통성의 부동산 정보 라이브러리 API를 사용하면, 최근의 실제 거래 데이터를 AI로부터 끌어낼 수 있게 됩니다.

Japan Data MCP 시리즈의 완결편

holiday·weather에 이은 세 번째 작품으로, Japan Data MCP 시리즈의 완결편입니다.

세 가지가 모두 갖춰지면 "이번 주말에 삿포로로 맨션 내람(집 구경)을 갈 수 있을지, 날씨와 공휴일과 시세를 한 번에 조사해줘"라는 질문에 Claude가 대답할 수 있게 됩니다.

기술적인 포인트

Cloudflare KV로 캐싱

weather-mcp는 요청할 때마다 기상청 API를 fetch하는 설계였지만, realestate-mcp는 Cloudflare KV(Cloudflare가 제공하는 무료 데이터 저장 영역)를 사용하여 캐싱하고 있습니다.

이유는 두 가지입니다. 국토교통성 API에는 속도 제한(Rate Limit)이 있다는 점, 그리고 부동산 거래 데이터는 분기별로 업데이트되므로 매번 fetch할 필요가 없다는 점입니다.

도구 호출 시
↓
Cloudflare KV에 동일한 쿼리의 캐시가 있는지 확인
...

KV란 무엇인가? Cloudflare가 제공하는 심플한 데이터 저장 서비스입니다. "키(Key, 검색 조건)"와 "밸류(Value, 취득 결과)"를 쌍으로 저장할 뿐인 구조로, DB만큼 복잡하지 않습니다. 무료 범위 내에서 사용할 수 있습니다.

API 키가 필요함

holiday-mcp와 weather-mcp는 API 키가 필요 없었지만, realestate-mcp는 국토교통성에 대한 신청이 필요합니다. 신청 폼을 통해 신청하면 영업일 기준 수일 내에 API 키가 발급됩니다. 키는 요청 헤더(Request Header)를 통해 전달하는 형식입니다.

응답(Response) 크기가 큼

부동산 거래 데이터는 한 번의 요청에 수백~수천 건의 JSON이 반환됩니다. 그대로 AI에게 전달하면 토큰(Token) 수가 방대해지기 때문에, 집계 및 요약(Summary)화하여 반환하도록 설계했습니다.

막혔던 부분 (솔직하게 작성합니다)

API 파라미터 이름이 생각했던 것과 달랐음

처음에 도도부현(Prefecture)을 지정하는 파라미터를 prefectureCode라고 생각하고 구현했더니 작동하지 않았습니다. 정답은 area였습니다.

공식 문서를 제대로 읽었다면 적혀 있었겠지만, 다른 API의 명명 규칙(Naming Convention)으로부터 추측하여 단정 지어버린 것이 원인이었습니다. 문서는 처음부터 전부 읽는다는 습관의 중요성을 다시 한번 배웠습니다.

Cloudflare API 토큰의 권한 설정

KV를 사용하기 위해서는 Cloudflare API 토큰에 「KV 읽기/쓰기 권한」을 추가해야 했습니다. 배포 전용 토큰(Deploy-only token)만으로는 부족하여 막혔으나, 커스텀 토큰(Custom token)으로 필요한 권한을 모두 부여함으로써 해결했습니다.

API 키 신청부터 취득까지 시간이 걸림

국토교통성(MLIT)의 API 키는 신청부터 발급까지 최대 1주일이 소요됩니다. 구현을 시작하기 전에 미리 API 키를 신청해 두는 것이 정답입니다. 신청을 먼저 해두면 코드가 완성될 즈음에는 키가 도착해 있을 것입니다.

Smithery 등록

등록 후 점수는 58/100이었습니다. japan-weather-mcp와 동일한 점수입니다.

3개 프로젝트의 점수를 정리하면 다음과 같습니다:

3개 모두 「No description」 상태이므로, 설명문과 아이콘을 정비하면 점수가 올라갈 것입니다. 향후 대응할 예정입니다.

등록 시 필요한 것은 가동 중인 서버 URL입니다.

사용법

Claude Desktop에 설정하기

claude_desktop_config.json에 다음 내용을 추가합니다.

{
"mcpServers": {
"japan-realestate-mcp": {
...

설정 후 Claude Desktop을 재시작하면 사용할 수 있습니다.

테스트용 프롬프트 예시

• "도쿄도 시부야구의 최근 맨션 거래 가격을 알려줘"
• "삿포로시 주오구의 단독주택 시세는 어느 정도야?"
• "홋카이도의 토지 거래 경향을 알려줘"

Japan Data MCP 시리즈 3종 완성

이로써 3종의 시리즈가 완성되었습니다. 3개를 동시에 사용하면 Claude가 일본 정부 기관 데이터를 원스톱(One-stop)으로 다룰 수 있게 됩니다.

「삿포로에서 맨션 구입을 검토 중. 이번 주말에 내람(집 구경)을 갈 수 있는지 확인하고 싶어」
→ Claude가 한꺼번에 답변:
【부동산 시세】삿포로시 주오구 맨션 중앙값 ●●●만 엔
...

직접 만들 수 있습니다

이 MCP 서버는 템플릿을 사용하여 만들었습니다.

• GitHub 템플릿 (DB 미포함 버전): https://github.com/kakarsatoshi-bot/mcp-template
• GitHub 템플릿 (Supabase DB 포함 버전): https://github.com/kakarsatoshi-bot/mcp-template-with-db
• 상세 튜토리얼 (Gumroad): https://tsukuras.gumroad.com/l/mcp-template

관련 MCP 시리즈

Discussion