🎁 korea-benefits-mcp

"내가 받을 수 있는 정부 지원금 알려줘"라고 Claude에게 물어보세요. 보조금24에 등록된 중앙부처·지자체 혜택 1만여 건에서 내 조건에 맞는 것을 찾아주는 MCP 서버

English · 빠른 시작 · 도구 · 어떻게 판정하나

이런 대화가 됩니다

나: 31살이고 수원 살아. 월세 지원 받을 수 있는 거 있어?

Claude: 월세 관련 사업 9건을 찾았어요. 대부분 소득과 무주택 여부에 따라 갈려요. 가구 소득이 기준중위소득의 몇 % 정도인지, 무주택인지 알려주시겠어요?

나: 무주택이고 소득은 중위소득 55% 정도, 직장 다녀.

Claude: 그럼 청년월세 지원(국토교통부), 주택금융공사 월세자금보증, 버팀목전세자금대출 대상이에요. 청년월세 지원은 월 최대 20만 원이고, 신청은 복지로에서…

• 🔍 1만여 건 전체에서 찾기: 중앙부처 사업부터 "서울특별시 마포구" 같은 구 단위 사업까지, 사는 곳에 맞게 거릅니다.

• ✅ 코드로 판정하고 LLM은 추측하지 않음: 보조금24가 구조화해 둔 자격조건(연령·성별·중위소득·생애·가구 상황)으로 판정합니다.

• ❓ 모르면 되묻기: 판정에 필요한 정보가 없으면 "가능/불가"를 지어내지 않고, 무엇을 물어봐야 하는지 돌려줍니다.

• ⏰ 마감 임박 알림: 신청기한에서 날짜를 읽어 곧 마감되는 혜택을 알려줍니다.

• ⚡ 빠름: 처음 한 번 전체 목록을 약 5초 만에 로컬에 받아 두고, 이후 검색은 즉시 끝납니다(하루 1회 자동 갱신).

Related MCP server: gov-support-mcp

🚀 빠른 시작

1. 인증키 발급 (3분)

1. 공공데이터포털에 가입합니다.

2. 행정안전부_대한민국 공공서비스 정보에서 활용신청을 누릅니다. 자동승인이라 바로 쓸 수 있습니다.

3. 마이페이지에서 인증키를 복사합니다. Encoding 키와 Decoding 키 중 아무거나 써도 됩니다.

2. Claude Desktop

claude_desktop_config.json에 추가하세요. (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\)

{
  "mcpServers": {
    "korea-benefits": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/RosieOh/korea-benefits-mcp", "korea-benefits-mcp"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_인증키" }
    }
  }
}

Claude Code

claude mcp add korea-benefits -e DATA_GO_KR_SERVICE_KEY=발급받은키 -- uvx --from git+https://github.com/RosieOh/korea-benefits-mcp korea-benefits-mcp

🧰 도구

프롬프트: benefit_checkup: 짧은 인터뷰로 혜택을 점검하고 "바로 신청 가능 / 확인 필요 / 마감 임박"으로 정리합니다.

🧠 어떻게 판정하나

보조금24 supportConditions는 서비스마다 50개 조건 코드를 제공합니다. 판정 규칙은 다음과 같습니다.

그룹 사이는 AND입니다. 결과는 세 가지로 나옵니다.

• eligible: 코드화된 조건을 모두 충족

• needs_info: 정보가 부족함. 무엇이 필요한지 함께 줍니다

• ineligible: 조건 미충족. 사유를 함께 줍니다

⚠️ 코드화된 조건만 봅니다. 재산 기준, 거주 기간 같은 세부 요건은 get_benefit_detail의 선정기준 원문으로 확인하세요. 최종 자격은 소관기관이 판단합니다.

실제 데이터에서 부딪힌 것들

• 자격조건은 조건 검색이 안 됩니다. 서비스ID 단건 조회만 지원해서 전량을 페이지 단위로 받아 로컬(SQLite)에서 매칭합니다. 1만 건 동기화가 약 5초, 호출 20여 회로 끝납니다.

• 지역 코드가 없습니다. 소관기관명으로 지역을 판별합니다. 서울특별시 강남구는 쉽지만 마포구시설관리공단, 구리도시공사, (재)남동문화재단처럼 시도가 빠진 기관이 많습니다. 그래서 동기화한 시군구 227곳으로 색인을 만들어 찾습니다. 중구, 강서구처럼 여러 시도에 있는 이름은 억지로 판별하지 않습니다.

• 행정구역이 바뀝니다. 2026년부터 광주광역시와 전라남도가 전남광주통합특별시로 옵니다. "광주", "전남"으로 입력해도 연결됩니다.

• 신청기한은 자유 텍스트입니다. "상시신청", "2026. 3. 2. ~ 2026. 12. 31.", "신청불필요", "예산 소진 시까지" 등이 섞여 있습니다. 확실히 읽히는 날짜만 쓰고 추측하지 않습니다.

🔒 개인정보

• 입력한 정보는 내 PC 밖으로 나가지 않습니다. 나이, 소득, 장애·임신 여부 같은 조건은 로컬에서만 매칭에 씁니다. 공공데이터포털에는 전체 목록의 페이지 번호와 서비스ID만 요청합니다.

• 로컬에 저장되는 것은 공개 혜택 목록뿐입니다. 사용자 프로필은 저장하지 않습니다. 캐시 위치는 아래 개발 항목을 참고하세요.

• 다만 대화 내용은 사용 중인 AI 서비스로 전달됩니다. Claude 등과 대화하며 입력한 내용은 그 서비스의 개인정보 정책을 따릅니다. 건강·장애 같은 민감한 정보는 필요한 만큼만 말하세요. 예: "장애가 있다" 대신 "장애인 대상 혜택도 보여줘".

🛠 개발

git clone https://github.com/RosieOh/korea-benefits-mcp && cd korea-benefits-mcp
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                               # 키 없이 전부 통과 (respx 목킹)

카탈로그 캐시 위치는 기본값이 %LOCALAPPDATA%\korea-benefits-mcp(Windows)나 ~/.cache/korea-benefits-mcp이고, KOREA_BENEFITS_CACHE_DIR로 바꿀 수 있습니다.

🗺 로드맵

• 온통청년 청년정책 API 연동(청년 정책의 소득·지역 조건을 더 세밀하게)

• 복지로 지자체 복지서비스와 중복 제거

• 기준중위소득 계산 도우미(가구원 수와 월소득으로 % 추정)

• 마감 일정 캘린더(ICS) 내보내기

• PyPI 배포

⚠️ 면책

공공데이터포털의 행정안전부 「대한민국 공공서비스 정보」를 이용한 참고용 도구입니다. 실제 수급 자격과 금액은 각 소관기관의 심사로 결정됩니다. 신청 전에 정부24·복지로의 공식 안내를 확인하세요. 이 프로젝트는 어떤 정부기관과도 제휴 관계가 없습니다.

English

korea-benefits-mcp is an MCP server that finds Korean government benefits (central ministries and local governments, 10,000+ programs) a person is eligible for, using the official Gov24 public service catalog from data.go.kr.

• Deterministic eligibility: matches age, gender, median-income bracket, life stage and household status against Gov24's structured condition codes. Nothing is guessed by the LLM.

• Asks instead of guessing: when information is missing, returns needs_info plus the questions to ask the user.

• Region-aware: filters local programs down to city/district level, even for agencies whose names omit the province.

• Deadlines: parses free-text application periods and lists programs closing soon.

Requires a free data.go.kr API key (auto-approved).

License

MIT