청약 도우미 — Claude·Codex용 MCP 서버

Claude와 Codex에서 내 청약 조건에 맞는 공고를 비교하고, 주거비·대출·자금 계획을 계산하고 저장하는 도구입니다. 같은 서비스 계정으로 연결하면 두 AI에서 같은 개인 자료를 이어서 사용할 수 있습니다.

Node.js만으로 실행할 수 있습니다. Docker는 선택 사항입니다. 이 저장소는 직접 운영하는 서버 프로그램이며, 다운로드만으로 공용 온라인 서버가 생기지는 않습니다.

최신 배포 ZIP 다운로드 · 전체 릴리스 · 운영·배포 안내

빠르게 시작하기

준비물은 Node.js 22.14 이상과 로컬 도구 연결을 지원하는 Codex 또는 Claude Code입니다. Node.js 다운로드에서 지원되는 LTS 버전을 설치하고 node --version으로 확인하세요. Node 22에서는 SQLite 실험 기능 경고가 나올 수 있습니다.

1. 위 ZIP을 다운로드해 압축을 풀고, package.json이 있는 폴더에서 터미널을 엽니다. Git을 사용한다면 다음으로 내려받습니다.

   git clone https://github.com/ANNJUNGCHAN/housing-mcp.git
   cd housing-mcp

2. Windows PowerShell, macOS 또는 Linux 터미널에서 실행합니다.

   npm ci
   npm run setup
   npm start

3. 초기 설정에서 사용할 이메일을 입력합니다. 설정 도구가 로컬 실행용 .env와 한 번만 사용하는 가입 링크를 준비합니다. 이미 있는 .env는 덮어쓰지 않습니다.

4. 서버가 실행된 상태에서 출력된 가입 링크를 브라우저로 열고 비밀번호를 정합니다. 이메일을 발송하는 기능은 없으며, 가입 링크는 24시간 동안 유효합니다.

5. 아래 방법으로 AI에 연결합니다. 로컬로 사용할 때는 이 터미널의 서버를 계속 실행해 둡니다.

여기서 만드는 계정은 이 청약 도우미 서버의 계정입니다. Claude·OpenAI 계정 비밀번호나 AI API 키를 입력하지 않습니다.

Related MCP server: NYC Property Data MCP Server

AI에 연결하기

Codex

Codex CLI가 설치된 터미널에서 실행합니다.

codex mcp add housing --url http://127.0.0.1:8787/mcp
codex mcp login housing --scopes housing --oauth-client-registration dcr

열리는 브라우저에서 청약 도우미 계정으로 로그인하고 연결 허용을 선택합니다. Codex 앱에서는 MCP 서버 설정에 같은 URL을 추가하고 인증할 수 있습니다.

Claude Code

claude mcp add --transport http --scope user housing http://127.0.0.1:8787/mcp

Claude Code 대화에서 /mcp를 열어 housing의 인증을 시작하고, 청약 도우미 계정으로 로그인해 연결을 허용합니다.

일반 Claude 웹·데스크톱·모바일

일반 Claude의 원격 연결은 인터넷에서 접근할 수 있는 HTTPS 서버가 필요합니다. 위의 127.0.0.1 주소는 같은 컴퓨터에서 쓰는 Codex·Claude Code용입니다.

운영자가 제공한 https://실제-서버-주소/mcp를 Claude의 사용자 지정 연결에 등록하세요. OAuth 등록 방법을 선택할 수 있으면 자동 등록 / Register automatically를 사용합니다. 별도 클라이언트 비밀키는 필요하지 않습니다. 조직 계정은 관리자의 연결 정책을 따릅니다.

서버를 직접 공개하려면 HTTPS 배포 안내를 따릅니다. 직접 Node.js를 실행하는 방법과 선택 사항인 Docker 구성을 제공합니다.

연결 후 이렇게 요청하세요

• “내 청약통장과 관심 지역을 등록해 줘. 모르는 조건은 미확인으로 남겨 줘.”

• “현재 공고를 찾고 내 조건과 비교해 줘. 원문 확인이 필요한 항목도 알려 줘.”

• “대출 3억 원, 연 4%, 30년이라는 가정으로 월별 상환액을 계산해 줘.”

• “이 후보와 자금 계획을 저장하고 다음에 다시 보여 줘.”

기능은 청약·통근 조건 저장, 청약홈·LH 공고 조회, 입력한 원문 조건 비교, 주거비 비교, 대출·완납기간·상환여력 계산, 후보·자금 계획 저장입니다. AI가 사용할 17개 도구와 입력 형식은 연결 시 자동으로 전달됩니다.

공공데이터 API 키는 선택 사항입니다

비용·대출 계산과 개인 조건·후보·계획 저장은 키 없이 사용할 수 있습니다. 청약홈·LH의 API 공고 목록 조회에는 공공데이터포털 일반 인증키와 해당 서비스 활용신청이 필요합니다.

키가 있다면 서버의 .env에 저장하고 재시작합니다.

DATA_GOV_API_KEY=발급받은_공공데이터포털_일반_인증키

키는 AI 대화나 도구 입력에 붙여넣지 않습니다. 키가 없거나 API가 실패하면 서버는 조회 불가·불완전 상태를 표시합니다. 연결한 AI가 웹 검색을 지원하면 공식 웹 공고를 별도로 확인하도록 요청할 수 있습니다. 이 서버 자체에 별도 AI 호출 비용이 발생하는 코드는 없습니다.

공고 목록은 최종 자격 확인이 아닙니다. 원문·정정 공고와 복합 자격은 별도로 확인하며 계산 결과는 입력한 가정에 따른 산술 결과입니다. 기존 시세 연구 DB, 가격 예측 모델, 청약 신청 제출, 자동 알림 발송은 포함하지 않습니다.

여러 사람이 함께 쓰기

사용 방법은 두 가지입니다.

공유 서버에서는 운영자가 npm run admin -- invite person@example.com으로 초대 링크를 만듭니다. 각 사용자는 자신의 계정으로 로그인하며 다른 사용자의 프로필·후보·계획에 접근할 수 없습니다. 같은 사람이 같은 서버 계정으로 연결한 Claude와 Codex는 저장 자료를 공유하지만 AI 대화 기록 자체가 동기화되지는 않습니다.

기본 데이터는 var/의 SQLite에 저장됩니다. 다른 서버로 옮길 때는 백업·복구가 필요합니다. 운영자는 서버 파일에 접근할 수 있으므로, 공유 서버 이용자는 운영 주체를 확인하고 사용하는 것이 좋습니다. .env·데이터 관리 및 백업에 자세한 내용을 정리했습니다.

업데이트와 문제 해결

Git으로 설치했다면 서버를 멈추고 git pull, npm ci를 실행한 뒤 다시 npm start로 시작합니다. ZIP으로 설치했다면 새 버전으로 교체하기 전에 .env와 데이터 폴더를 따로 백업하고 새 버전에 복원합니다. 업데이트할 때 개인 데이터 폴더를 덮어쓰거나 삭제하지 않습니다.

문제를 올릴 때는 비밀번호, 초대·재설정 링크, API 키, 개인 조건과 데이터 파일을 제외해 주세요.

개발·검증

npm run check
npm test

테스트는 임시 DB와 합성 입력·모의 API를 사용합니다. GitHub Actions는 Windows·Ubuntu의 Node.js 22.14와 24에서 검사하도록 구성되어 있습니다. Actions 실행 결과와 검증 범위를 확인할 수 있습니다. 실제 Claude·Codex 계정 연결과 공개 HTTPS 운영은 배포 환경에서 별도 확인해야 합니다.

소프트웨어는 MIT 라이선스입니다. 외부 라이브러리와 공공데이터 이용 조건은 THIRD_PARTY_NOTICES.md를 참고하세요.