⚠️ 서비스 종료 안내 본 MCP 서버는 2026-08-23부로 fly.io 배포를 종료했습니다. 코드는 개발 참고용으로 저장소에 남겨둡니다.

realestate-stats-mcp

한국부동산원(R-ONE) 부동산통계 Open API를 위한 MCP 서버. 아파트 매매/전세가격지수, 지가변동률, 부동산 거래현황 등 R-ONE이 제공하는 수백 개 통계표를 이름으로 검색하고 실제 수치를 조회할 수 있는 범용 통계조회 도구입니다.

이 API는 통계마다 별도 엔드포인트가 있는 게 아니라, 통계표코드(STATBL_ID)로 원하는 통계를 지정해 조회하는 구조입니다. 그래서 이 MCP도 통계별 전용 툴이 아니라 3개의 범용 툴로 모든 통계표를 다룹니다.

제공 도구 (Tools)

통계표를 이름/키워드로 검색합니다. 예: "아파트 매매", "지가변동률", "실거래가" → STATBL_ID, 통계표명, 주기, 데이터 존재 기간을 반환합니다.

특정 통계표의 지역/분류/그룹 코드를 조회합니다. 실제 데이터를 조회하기 전에 지역 코드(CLS_ID) 등을 알아내는 용도입니다.

실제 통계 수치를 조회합니다. 단위(UI_NM)와 함께 값을 반환합니다.

주기코드(DTACYCLE_CD)별 시점 형식

pip install -r requirements.txt
cp .env.example .env
# .env에 REB_API_KEY 입력 (R-ONE 사이트에서 직접 발급 — 공공데이터포털 키와 다를 수 있음)
python server.py

변수명	설명
`REB_API_KEY`	한국부동산원 R-ONE 오픈API 인증키 (`https://www.reb.or.kr/r-one/portal/openapi/openApiActKeyPage.do` 에서 발급)

fly launch --no-deploy
fly secrets set REB_API_KEY=발급받은키
flyctl deploy

배포 후 Claude.ai 커넥터 연결 시 주소 끝에 /mcp를 붙여서 연결하세요. 예: https://realestate-stats-mcp.fly.dev/mcp

1회 요청 최대 1,000건 (ERROR-336)
일별 트래픽 제한 있음 (ERROR-337, 초과 시 익일까지 대기)
Type=json 응답은 서버 인코딩 버그로 한글이 깨진다. 이 MCP는 이 문제를 피하기 위해 항상 기본(XML) 응답을 사용하고 내부에서 XML을 파싱한다. (직접 API를 호출할 경우 참고)
STATBL_ID 없이 SttsApiTbl.do 호출 시 전체 통계표 목록(738건, 실측 시점 기준)이 정상 반환된다. 이 MCP는 이를 최초 1회 호출해 인메모리로 캐시하고, search_statistics는 STATBL_NM 문자열 매칭으로 필터링한다. (캐시는 서버 프로세스 생명주기 동안만 유지 — 재시작 시 리셋)
선택 파라미터(GRP_ID/CLS_ID/ITM_ID)를 일부만 채워도 500 에러는 재현되지 않는다. 존재하지 않는 ID를 넣으면 에러가 아니라 INFO-200(데이터 없음, 빈 결과)으로 정상 응답한다.
응답 루트 구조가 두 가지다: 정상/빈 결과는 <엔드포인트명><head><RESULT>..., 에러(예: ERROR-300)는 <head> 없이 루트가 바로 <RESULT>. reb_api.py가 두 형태를 모두 처리한다.

전체 후보는 search_statistics("매매"), search_statistics("거래"), search_statistics("가격") 등으로 직접 조회 가능(각 100건 이상). 위 표는 대표적인 항목만 발췌한 것.

한국부동산원 제공 공공데이터, 이용허락범위 제한 없음(공공데이터포털 명시 기준).

한국부동산원(REB) R-ONE 부동산통계 Open API — https://www.reb.or.kr/r-one/openapi