청약홈 API MCP 서버

청약홈 청약접수 경쟁률 및 특별공급 신청현황 조회 서비스를 위한 MCP (Model Context Protocol) 서버입니다.

설치 및 실행

# 의존성 설치
npm install

# TypeScript 빌드
npm run build

# 서버 실행
npm start

# 개발 모드 실행
npm run dev

사용 가능한 도구 (Tools)

1. get_apt_competition

APT 분양정보/경쟁률 조회

• 매개변수: house_manage_no, pblanc_no, reside_secd

2. get_urban_officetel_competition

오피스텔/도시형/민간임대/생활숙박시설 분양정보/경쟁률 조회

• 매개변수: house_manage_no, pblanc_no

3. get_public_private_rental_competition

공공지원 민간임대 분양정보/경쟁률 조회

• 매개변수: house_manage_no, pblanc_no, spsply_knd_code

4. get_cancel_resupply_competition

취소후재공급 분양정보/경쟁률 조회

• 매개변수: house_manage_no, pblanc_no

5. get_remaining_household_competition

잔여세대 분양정보/경쟁률 조회

• 매개변수: house_manage_no, pblanc_no, remndr_hshld_pblanc_tycd

6. get_apt_score

APT 분양정보 당첨가점 조회

• 매개변수: house_manage_no, pblanc_no, reside_secd

7. get_optional_supply_competition

임의공급 분양정보/경쟁률 조회

• 매개변수: house_manage_no, pblanc_no

8. get_apt_special_supply_status

APT 특별공급 신청현황 조회

• 매개변수: house_manage_no, pblanc_no

코드 참조

거주구분 코드

• 01: 해당지역
• 02: 기타지역
• 03: 기타경기

공급유형 구분 코드

• 00: 일반공급
• SY: 청년
• SN: 신혼부부
• SO: 고령자

사전/사후 구분 코드

• 01: 사후
• 02: 사전

💰 중요: 금액 단위 안내

청약홈 API에서 제공하는 분양가 관련 수치는 모두 만원 단위입니다.

Claude를 통해 이 API를 사용할 때, Claude는 다음과 같이 금액을 해석합니다:

• API 응답값: 19800 → 1억 9천 8백만원
• API 응답값: 85000 → 8억 5천만원
• API 응답값: 123456 → 12억 3천 4백 5십 6만원

Claude 사용 시 프롬프트 예시

"청약홈 API의 분양가 정보를 조회해주세요. 
금액은 만원 단위이므로 읽기 쉬운 한국식 표현으로 변환해서 알려주세요."

MCP 설정

Claude Desktop의 설정 파일에 다음과 같이 추가:

{
  "mcpServers": {
    "applyhome-api": {
      "command": "npx",
      "args": ["@minjunkwon/applyhome-api-mcp-server"]
    }
  }
}

NPM 패키지로 설치

# 전역 설치
npm install -g @minjunkwon/applyhome-api-mcp-server

# 또는 npx로 직접 실행 (권장)
npx @minjunkwon/applyhome-api-mcp-server