@minjunkwon/public-housing-mcp-server/README.md

MCP server for public housing information in South Korea - 한국 공공주택 정보 조회 MCP 서버

# 공공주택 정보 조회 MCP 서버 🏠

[![npm version](https://badge.fury.io/js/@minjunkwon%2Fpublic-housing-mcp-server.svg)](https://badge.fury.io/js/@minjunkwon%2Fpublic-housing-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

한국의 공공주택(임대/분양) 모집공고 정보를 조회할 수 있는 MCP(Model Context Protocol) 서버입니다.

Claude Desktop에서 실시간 공공주택 정보를 자연어로 조회할 수 있습니다.

## 기능

### 제공 도구

1. **get_rental_housing** - 공공임대주택 모집공고 조회
2. **get_sale_housing** - 공공분양주택 모집공고 조회

### 지원 파라미터

#### 공공임대주택 조회
- **region** (필수): 광역시도명 (예: "서울특별시", "경기도")
- **district** (선택): 시군구명 (예: "강남구", "수원시")
- **supplyType** (선택): 공급유형 (예: "국민임대", "행복주택")
- **isLongTermLease** (선택): 전세형 여부 (true/false)
- **rentRange** (선택): 월임대료 구간 (예: "10~20만원 미만")
- **pageSize** (선택): 페이지당 데이터 개수 (기본값: 10)
- **pageNumber** (선택): 페이지 번호 (기본값: 1)

#### 공공분양주택 조회
- **region** (필수): 광역시도명
- **district** (선택): 시군구명
- **housingType** (선택): 주택유형 (예: "연립주택", "다세대주택")
- **pageSize** (선택): 페이지당 데이터 개수
- **pageNumber** (선택): 페이지 번호

## 설치

### NPM으로 설치
```bash
npm install -g @minjunkwon/public-housing-mcp-server
```

### 로컬 개발
```bash
git clone https://github.com/minjunkwon/public-housing-mcp-server.git
cd public-housing-mcp-server
npm install
npm run build
npm start
```

## Claude Desktop 연동

### NPM 글로벌 설치 후 설정
`~/Library/Application Support/Claude/claude_desktop_config.json` 파일에 추가:
```json
{
  "mcpServers": {
    "public-housing": {
      "command": "npx",
      "args": ["@minjunkwon/public-housing-mcp-server"]
    }
  }
}
```

### 로컬 개발 설정
```json
{
  "mcpServers": {
    "public-housing": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/public-housing-mcp-server"
    }
  }
}
```

자세한 내용은 `CLAUDE_DESKTOP_SETUP.md` 참고

## 테스트 결과

✅ **API 연동 성공**: 실제 공공데이터포털 API와 정상 연동  
✅ **응답 파싱 완료**: JSON 형태 응답을 올바르게 파싱  
✅ **데이터 포맷팅**: 사용자 친화적 형태로 데이터 가공  
✅ **Claude Desktop 호환**: MCP 표준 인터페이스 구현  
✅ **자동 설정 스크립트**: 원클릭 Claude Desktop 연동

## Claude와 함께 사용하기

Claude가 이 MCP 서버를 사용할 때, 다음과 같은 자연어 요청을 이해하고 적절한 파라미터로 변환합니다:

### 사용 예시

1. **"서울 강남구 국민임대 주택 알려줘"**
   - region: "서울특별시"
   - district: "강남구" 
   - supplyType: "국민임대"

2. **"경기도 행복주택 전세형으로 찾아줘"**
   - region: "경기도"
   - supplyType: "행복주택"
   - isLongTermLease: true

3. **"부산 분양주택 연립주택만 보여줘"**
   - region: "부산광역시"
   - housingType: "연립주택"

4. **"임대료 10만원대 주택 찾아줘"**
   - rentRange: "10~20만원 미만"

## 지원 지역

### 광역시도
- 서울특별시, 부산광역시, 대구광역시, 인천광역시
- 광주광역시, 대전광역시, 울산광역시, 세종특별자치시  
- 경기도, 강원도, 충청북도, 충청남도
- 전라북도, 전라남도, 경상북도, 경상남도, 제주특별자치도

### 주요 시군구
- 서울: 25개 자치구 (강남구, 서초구, 송파구 등)
- 경기: 주요 시군 (수원시, 성남시, 고양시, 용인시 등)
- 기타 광역시: 각 지역 구군

## 공급유형

### 임대주택
- 영구임대, 국민임대, 50년임대, 매입임대
- 10년임대, 5년임대, 장기전세, 전세임대
- 행복주택, 공공지원민간임대

### 주택유형 (분양)
- 연립주택, 다세대주택, 단독주택
- 오피스텔, 다가구주택

## API 정보

- **데이터 출처**: 공공데이터포털 (data.go.kr)
- **서비스**: 공공임대주택 모집공고 서비스
- **업데이트**: 실시간 공공데이터 연동