KRE-MCP

jaypakdevkr가 만드는 한국 아파트 실거래가 MCP 서버입니다. Python 3.10 이상에서 실행되며, 공식 MCP Python SDK의 stdio 전송을 사용합니다.

데이터 출처는 국토교통부 공공데이터포털 API입니다. 한국부동산원 R-ONE 통계 API는 포함하지 않습니다. korea-realestate-mcp와 별개의 독립 패키지입니다.

제공 도구

두 도구는 동일한 입력을 받습니다.

지역코드는 행정표준코드관리시스템에서 확인합니다. 이 버전에는 지역명 검색, 전월세 조회, 시세 분석 기능은 포함하지 않습니다.

API 준비

공공데이터포털에서 아래 두 API 각각 활용신청 후 승인 상태를 확인하세요.

• 국토교통부_아파트 매매 실거래가 자료
• 국토교통부_아파트 분양권전매 실거래가 자료

일반 인증키(Decoding)를 PUBLIC_DATA_API_KEY 환경변수에 설정합니다. Encoding 키도 1회 디코딩하여 처리합니다. 키는 도구 입력에 넣지 않습니다. 서버는 .env를 자동으로 읽지 않으므로 클라이언트 env 또는 셸에 설정하세요.

설치 및 실행

PyPI 릴리스가 게시된 후:

uvx kre-mcp

또는:

pip install kre-mcp
kre-mcp

kre-mcp --version으로 설치를 확인합니다. 서버 실행 시 화면에 대화형 프롬프트가 나오지 않는 것이 정상입니다. MCP 클라이언트가 표준입출력으로 연결합니다.

MCP 클라이언트 설정

Claude Desktop 등 stdio MCP 클라이언트의 서버 설정에 추가하세요. uvx를 찾지 못하면 command에 설치된 uvx의 절대 경로를 넣으세요.

{
  "mcpServers": {
    "kre-mcp": {
      "command": "uvx",
      "args": ["kre-mcp==0.1.0"],
      "env": {
        "PUBLIC_DATA_API_KEY": "본인의 공공데이터포털 인증키"
      }
    }
  }
}

교육 실습에서는 수강생마다 본인의 API 키를 사용하세요.

실습 질문

• “지역코드 11680, 2026년 1월 아파트 매매 거래 10건을 조회해줘.”
• “같은 지역·월의 분양권 전매 거래도 조회해줘.”
• “다음 페이지가 있으면 이어서 조회하고 취소 거래를 구분해줘.”

결과 해석

items는 API 원본 필드를 공백 정리한 문자열로 반환합니다. dealAmount는 만원, excluUseAr는 **㎡**입니다. total_count는 API 전체 건수, returned_count는 현재 페이지 건수입니다. has_next=true이면 page를 1 늘려 추가 조회하세요. 필터링하지 않으므로 cdealType, cdealDay로 취소 거래를 확인해야 합니다. 한 페이지로 전체 평균·시세를 계산하지 마세요. 신고 지연, 취소, 정정으로 결과가 바뀔 수 있습니다.

로컬 개발

uv sync --locked
uv run pytest -q
uv run ruff check .
uv run python -m kre_mcp
uv build
uv run twine check dist/*

테스트는 실제 API 키 없이 mock HTTP와 실제 stdio MCP 연결을 검증합니다. 네트워크 오류에는 인증키가 포함된 요청 URL을 출력하지 않습니다.

PyPI 배포 (관리자)

GitHub Actions의 publish.yml은 테스트·빌드 후 PyPI Trusted Publishing(OIDC)으로 배포합니다. PyPI 토큰을 저장소에 저장하지 않습니다.

최초 1회 PyPI Publishing 설정의 새 pending publisher에 다음 값을 등록하세요.

그다음 GitHub Actions에서 Publish to PyPI 워크플로를 main 브랜치로 수동 실행합니다. 후속 배포는 pyproject.toml의 버전을 올리고 uv lock 후 main에 반영하여 실행하세요. 이미 배포한 버전은 재업로드할 수 없습니다.

라이선스

MIT. 데이터 이용 조건은 각 공공데이터포털 API 안내를 따릅니다.