# korea-realestate-mcp

한국 부동산(아파트) 실거래가 조회 및 분석을 위한 MCP(Model Context Protocol) 서버입니다.

AI 에이전트(Claude Desktop, Cursor, Claude Code 등)에서 자연어로 아파트 매매/전월세 시세를 조회하고 분석할 수 있습니다.

> 한국 부동산 데이터를 제공하는 **최초의 MCP 서버**입니다.

## 제공 도구

| 도구 | 설명 |
|------|------|
| `realestate_search_apt_trade` | 아파트 매매 실거래가 조회 |
| `realestate_search_apt_rent` | 아파트 전월세 실거래가 조회 |
| `realestate_get_region_code` | 지역명 → 법정동 코드 조회 (퍼지 매칭) |
| `realestate_analyze_price_trend` | 시세 추이 분석 (월별 통계, 변동률) |
| `realestate_compare_regions` | 2~5개 지역 시세 비교 |
| `realestate_analyze_rent_ratio` | 매매가 대비 전세가율 분석 |
| `realestate_get_apt_summary` | 특정 아파트 단지 종합 요약 |

## 설치

### uvx (권장)

```bash
uvx korea-realestate-mcp
```

### pip

```bash
pip install korea-realestate-mcp
```

## 설정

### 1. API 키 발급

[공공데이터포털](https://www.data.go.kr)에서 회원가입 후 아래 API의 활용 신청을 합니다:

- **국토교통부_아파트매매 실거래자료** ([링크](https://www.data.go.kr/data/15126469/openapi.do))
- **국토교통부_아파트 전월세 자료** ([링크](https://www.data.go.kr/data/15126471/openapi.do))

신청 즉시 승인되며, 마이페이지에서 **서비스 키(Decoding)**를 복사합니다.

### 2. Claude Desktop 설정

`claude_desktop_config.json`에 아래를 추가합니다:

```json
{
  "mcpServers": {
    "korea-realestate": {
      "command": "uvx",
      "args": ["korea-realestate-mcp"],
      "env": {
        "PUBLIC_DATA_API_KEY": "<발급받은 서비스 키>"
      }
    }
  }
}
```

### 3. Claude Code 설정

```bash
export PUBLIC_DATA_API_KEY="<발급받은 서비스 키>"
claude mcp add korea-realestate -- uvx korea-realestate-mcp
```

## 사용 시나리오

### 1. 아파트 시세 조회

> "강남구 아파트 최근 시세 알려줘"

`realestate_search_apt_trade`가 호출되어 최근 거래 내역을 Markdown 테이블로 반환합니다.

### 2. 특정 단지 시세 추이

> "래미안대치팰리스 84㎡ 최근 1년 시세 추이 보여줘"

`realestate_analyze_price_trend`가 월별 평균가, 변동률, 거래량을 분석합니다.

### 3. 지역 비교

> "분당 vs 일산 아파트 가격 비교해줘"

`realestate_compare_regions`가 지역별 평균가, 중앙값, ㎡당 단가를 비교합니다.

### 4. 전세가율 분석

> "분당 전세가율 어때?"

`realestate_analyze_rent_ratio`가 매매가 대비 전세가율과 갭투자 금액을 산출합니다.

### 5. 단지 종합 정보

> "판교 힐스테이트 종합 정보"

`realestate_get_apt_summary`가 최근 거래, 면적대별 시세, 전세가율을 요약합니다.

## 데이터 출처

- [국토교통부 실거래가 공개시스템](https://rt.molit.go.kr)
- [공공데이터포털 API](https://www.data.go.kr)

## 기술 스택

- Python 3.10+
- [FastMCP](https://github.com/modelcontextprotocol/python-sdk) (MCP Python SDK)
- httpx (비동기 HTTP)
- SQLite 캐시 (aiosqlite)
- pandas (데이터 분석)

## 라이선스

[MIT](LICENSE)