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

# realestate-mcp

국토교통부 실거래가 공공데이터(data.go.kr)를 [MCP](https://modelcontextprotocol.io)
도구로 제공하는 서버입니다. 아파트/연립다세대/단독다가구/오피스텔의 매매·전월세
실거래가를 지역코드+계약년월로 조회합니다.

## 제공 도구 (8개)

| 도구명 | 설명 |
|---|---|
| `get_apt_trade` | 아파트 매매 실거래가 |
| `get_apt_rent` | 아파트 전월세 실거래가 |
| `get_sh_trade` | 단독/다가구 매매 실거래가 |
| `get_sh_rent` | 단독/다가구 전월세 실거래가 |
| `get_rh_trade` | 연립다세대 매매 실거래가 |
| `get_rh_rent` | 연립다세대 전월세 실거래가 |
| `get_offi_trade` | 오피스텔 매매 실거래가 |
| `get_offi_rent` | 오피스텔 전월세 실거래가 |

공통 입력: `regionCode`(법정동 앞 5자리, 예: 서울 종로구 `11110`), `dealYearMonth`(YYYYMM),
`pageNo`(선택), `numOfRows`(선택, 기본 10)

## 배포

Fly.io에 HTTP(streamable) MCP 서버로 배포되어 있습니다: https://realestate-mcp-hlucent.fly.dev/mcp

서버가 자체 data.go.kr 인증키를 사용하므로 별도의 `?key=` 파라미터 없이 위 주소로
바로 연결하면 됩니다. (과거의 `?key=본인_인증키` 방식은 더 이상 사용하지 않습니다.)

같은 IP의 과도한 호출을 막기 위해 rate limit이 적용되어 있습니다
(분당 3회, 24시간 30회 초과 시 429). 일반적인 대화형 사용에는 지장이 없습니다.

## 로컬 개발

```bash
npm install
cp .env.example .env   # DATA_GO_KR_SERVICE_KEY 입력 (서버가 사용할 자체 인증키)
npm run dev             # http://localhost:8080/mcp
```

배포 환경에서는 `DATA_GO_KR_SERVICE_KEY`를 Fly secrets로 주입합니다
(`fly secrets set DATA_GO_KR_SERVICE_KEY=...`). 코드에는 절대 하드코딩하지 않습니다.

## 문서
- 아키텍처/설계: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- API별 상세 스펙 요약: [`docs/api-spec/`](docs/api-spec/)
- 개발일지(자동 생성): [`docs/devlog/`](docs/devlog/)

## 개발 참고
Claude Code로 작업 시 `CLAUDE.md`를 먼저 읽으세요. 토큰 절약을 위한 작업 규칙이 정리되어 있습니다.