<div align="center">

# 🎁 korea-benefits-mcp

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

[![CI](https://github.com/RosieOh/korea-benefits-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/RosieOh/korea-benefits-mcp/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![MCP](https://img.shields.io/badge/MCP-2.x-8A2BE2)
![License](https://img.shields.io/badge/license-MIT-green)

[English](#english) · [빠른 시작](#-빠른-시작) · [도구](#-도구) · [어떻게 판정하나](#-어떻게-판정하나)

<!-- TODO: "31살 수원 사는 직장인인데 월세 지원 받을 수 있어?" → 되묻기 → 결과까지 GIF를 docs/demo.gif로 넣고 주석 해제
<img src="docs/demo.gif" alt="demo" width="720">
-->

</div>

---

## 이런 대화가 됩니다

> **나:** 31살이고 수원 살아. 월세 지원 받을 수 있는 거 있어?
>
> **Claude:** 월세 관련 사업 9건을 찾았어요. 대부분 **소득**과 **무주택 여부**에 따라 갈려요. 가구 소득이 기준중위소득의 몇 % 정도인지, 무주택인지 알려주시겠어요?
>
> **나:** 무주택이고 소득은 중위소득 55% 정도, 직장 다녀.
>
> **Claude:** 그럼 **청년월세 지원**(국토교통부), **주택금융공사 월세자금보증**, **버팀목전세자금대출** 대상이에요. 청년월세 지원은 월 최대 20만 원이고, 신청은 복지로에서…

- 🔍 **1만여 건 전체에서 찾기**: 중앙부처 사업부터 "서울특별시 마포구" 같은 구 단위 사업까지, 사는 곳에 맞게 거릅니다.
- ✅ **코드로 판정하고 LLM은 추측하지 않음**: 보조금24가 구조화해 둔 자격조건(연령·성별·중위소득·생애·가구 상황)으로 판정합니다.
- ❓ **모르면 되묻기**: 판정에 필요한 정보가 없으면 "가능/불가"를 지어내지 않고, **무엇을 물어봐야 하는지** 돌려줍니다.
- ⏰ **마감 임박 알림**: 신청기한에서 날짜를 읽어 곧 마감되는 혜택을 알려줍니다.
- ⚡ **빠름**: 처음 한 번 전체 목록을 약 5초 만에 로컬에 받아 두고, 이후 검색은 즉시 끝납니다(하루 1회 자동 갱신).

## 🚀 빠른 시작

### 1. 인증키 발급 (3분)
1. [공공데이터포털](https://www.data.go.kr)에 가입합니다.
2. [행정안전부_대한민국 공공서비스 정보](https://www.data.go.kr/data/15113968/openapi.do)에서 **활용신청**을 누릅니다. 자동승인이라 바로 쓸 수 있습니다.
3. 마이페이지에서 인증키를 복사합니다. Encoding 키와 Decoding 키 중 아무거나 써도 됩니다.

### 2. Claude Desktop

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

```json
{
  "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

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

## 🧰 도구

| 도구 | 설명 |
|---|---|
| `find_benefits` | ⭐ 나이·성별·거주지·소득·상황으로 받을 수 있는 혜택 찾기. 결과를 **가능 / 정보 부족**으로 나누고 **되물을 질문**도 줍니다 |
| `check_eligibility` | 특정 혜택 하나의 자격 판정과 **불가 사유** |
| `get_benefit_detail` | 선정기준 원문, 지원내용, 신청방법, 구비서류, 문의처, 온라인 신청 링크 |
| `search_benefits` | 키워드 검색(자격 판정 없이). 예: 산후조리, 전기차, 청년 주거 |
| `upcoming_deadlines` | N일 안에 신청 마감되는 혜택 |
| `list_profile_options` | 입력할 수 있는 상황 목록(직장인, 구직자, 임산부, 1인가구, 무주택…) |
| `catalog_status` / `refresh_catalog` | 로컬 카탈로그 상태 확인 / 즉시 갱신 |

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

## 🧠 어떻게 판정하나

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

| 그룹 | 예시 코드 | 판정 규칙 |
|---|---|---|
| 성별 | JA0101 남성, JA0102 여성 | 한쪽만 켜져 있을 때만 제한 |
| 연령 | JA0110 ~ JA0111 | 0은 하한 없음, 100 이상(원천 데이터의 120·200)은 상한 없음 |
| 중위소득 | JA0201(0~50%) … JA0205(200% 초과) | 사용자 %가 속한 구간이 켜져 있어야 함 |
| 생애·직업 | 임산부, 대학생, 구직자, 장애인 … | **그룹 안은 OR**, "해당사항없음"이 켜져 있으면 누구나 |
| 가구 | 한부모, 다자녀, 1인가구, 무주택 … | 위와 같음 |
| 소상공인·법인 | JA11xx, JA2xxx | 개인으로 찾을 때 제외 |

그룹 사이는 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 등과 대화하며 입력한 내용은 그 서비스의 개인정보 정책을 따릅니다. 건강·장애 같은 민감한 정보는 필요한 만큼만 말하세요. 예: "장애가 있다" 대신 "장애인 대상 혜택도 보여줘".

## 🛠 개발

```bash
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·복지로의 공식 안내를 확인하세요. 이 프로젝트는 어떤 정부기관과도 제휴 관계가 없습니다.

---

<a id="english"></a>

## 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](https://www.data.go.kr/data/15113968/openapi.do) API key (auto-approved).

## License

MIT