nezip (내집)

내집마련을 위한 똑똑한 AI 아파트 분석 서비스

국토교통부 실거래가 API를 이용해 아파트 실거래가 변동율을 조회하고, 강남3구 기준 아파트 대비 상승 추종률을 분석하는 CLI / MCP 서버.

Claude Code의 nezip 스킬과 MCP 서버로 연동하여 자연어로 아파트 실거래가를 조회할 수 있다.

사전 요구사항

• Claude Code CLI (claude)
• 국토부 실거래가 API 키

API 키 발급 방법 (펼치기)

API가 정상 동작하려면 아래 세 가지가 모두 갖춰져야 한다.

a) 공공데이터포털 회원가입 data.go.kr 에서 회원가입

b) 활용신청 완료 국토부 아파트매매 실거래가 자료 페이지에서 활용신청 버튼 클릭 후 승인 대기 (보통 즉시~수 시간 내 자동 승인)

c) API 키 확인 및 디코딩 마이페이지 → 인증키 발급현황에서 일반 인증키를 확인한다. 키에 %2B, %2F 등 URL 인코딩 문자가 포함된 경우, 디코딩된 값을 사용해야 한다.

%2B → +
%2F → /
%3D → =

Claude Code 연동 설치

아래 메시지를 복사해서 Claude Code에 붙여넣으면 설치를 자동으로 진행해준다.

https://raw.githubusercontent.com/chaewonkong/nezip/main/README.md 를 읽고, nezip을 설치해줘. MOLIT_API_KEY는 내가 직접 설정할게.

1. 바이너리 설치

curl -fsSL https://raw.githubusercontent.com/chaewonkong/nezip/main/install.sh | sh

설치 경로를 바꾸고 싶으면:

INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/chaewonkong/nezip/main/install.sh | sh

기본 설치 경로: root 권한이 있으면 /usr/local/bin, 없으면 ~/.local/bin. 설치 후 출력되는 경로를 확인해둔다.

2. API 키 설정

MCP 서버를 등록하기 전에 반드시 API 키를 먼저 설정해야 한다. MCP 서버는 등록 즉시 실행되므로, 이후 키를 추가해도 재시작 전까지 반영되지 않는다.

~/.claude/settings.json의 env 섹션에 추가:

{
  "env": {
    "MOLIT_API_KEY": "<URL 디코딩된 API 키>"
  }
}

3. MCP 서버 등록

먼저 API 키가 올바르게 등록되었는지 확인한다:

grep -q '"MOLIT_API_KEY"' ~/.claude/settings.json \
  && echo "✓ API 키 확인됨. MCP 서버를 등록합니다." \
  && claude mcp add --scope user nezip ~/.local/bin/nezip mcp \
  || echo "✗ API 키가 없습니다. 2단계로 돌아가 settings.json에 MOLIT_API_KEY를 먼저 추가하세요."

설치 경로가 다르면 1단계에서 확인한 경로로 대체한다. (예: /usr/local/bin/nezip)

등록 확인:

claude mcp list

4. nezip 스킬 설치

mkdir -p ~/.claude/skills/nezip
curl -fsSL https://raw.githubusercontent.com/chaewonkong/nezip/main/SKILL.md \
  -o ~/.claude/skills/nezip/SKILL.md

5. Claude Code 재시작

Claude Code를 재시작한다. settings.json의 env는 시작 시점에만 로드되므로, 재시작 후에야 MCP 서버가 MOLIT_API_KEY를 인식하고 정상 동작한다.

검증

Claude Code에서 직접 확인:

apt_search(lawd_cd: "11710")          → 송파구 아파트 목록
apt_analyze(apt_name: "헬리오시티", area: 84, lawd_cd: "11710")  → 분석 결과

nezip 스킬 사용법

설치 후 Claude Code에서 자연어로 요청:

/nezip 헬리오시티 84
/nezip 마포래미안푸르지오 59
아파트 실거래가 조회해줘 - 래미안퍼스티지 84㎡
판교 파크타운 59 분석해줘

CLI 직접 사용

MCP 없이 터미널에서 직접 사용할 수도 있다.

아파트 목록 조회

nezip search --lawd <LAWD_CD>
nezip search --lawd 41135

실거래가 분석

nezip --apt <아파트명> --area <면적㎡> --lawd <LAWD_CD> [--human]

• --apt: API에 등록된 정확한 이름 (search로 확인 후 사용)
• --area: 전용면적(㎡)
• --lawd: 5자리 법정동코드
• --human: 텍스트 리포트 출력. 없으면 JSON stdout

nezip search --lawd 41135
nezip --apt "파크타운(서안)" --area 59 --lawd 41135
nezip --apt "헬리오시티" --area 84 --lawd 11710 --human

출력 (JSON)

{
  "target": {
    "name": "헬리오시티",
    "area": 84,
    "current": 273500,
    "current_month": "202604",
    "y1": 257000,
    "y1_month": "202505",
    "y1_pct": 6.42,
    "y3": 195000,
    "y3_month": "202306",
    "y3_pct": 40.26
  },
  "gangnam3": {
    "avg_y1_pct": 4.15,
    "avg_y3_pct": 39.83,
    "breakdown": [...]
  },
  "follow_rate_y1": 154.6,
  "follow_rate_y3": 101.1,
  "cache_used": false,
  "warnings": []
}

구조

nezip/
├── cmd/nezip/
│   ├── main.go          # CLI 진입점 (analyze / search / cache / mcp 서브커맨드)
│   └── mcp.go           # MCP stdio 서버 (apt_search, apt_analyze tool 등록)
├── internal/
│   ├── api/client.go    # 국토부 HTTP 클라이언트 (병렬 goroutine)
│   ├── cache/           # SQLite 캐시 (~/.nezip.db)
│   ├── calc/            # 변동율·추종율 계산
│   ├── db/              # sqlc 생성 코드 (직접 수정 금지)
│   ├── report/          # JSON / --human 출력 포맷
│   └── service/         # 핵심 로직 (Search, Analyze) — CLI·MCP 공유
├── SKILL.md             # nezip 스킬 정의
├── sqlc.yaml
└── go.mod

환경변수

변수	설명
MOLIT_API_KEY	국토부 실거래가 API 인증키 (URL 디코딩된 값)