# comwel-mcp — 근로복지공단 산재판례·질병판정서·심사결정서 MCP

Claude가 근로복지공단의 **업무상질병 판정서**, **산재 심사청구 결정서**, **산재 판례 판결문**을 직접 검색하고, 원문을 읽고,
인용할 문장이 원문과 글자 그대로 같은지 대조할 수 있게 해 주는 MCP 서버입니다.

> - 근로복지공단의 공식 도구가 아닙니다. 공단이 [공공데이터포털](https://www.data.go.kr)에 공개한 API를 이용하는 개인 제작 도구입니다.
> - 검색 결과는 판단을 돕는 참고 자료이며 법률 자문이 아닙니다. 서면에 인용할 때는 반드시 원문을 확인하세요.

## 무엇을 할 수 있나요

Claude에게 이렇게 물어보면 됩니다.

- "급식실 조리흄 폐암으로 **인정**된 질병판정서 찾아줘"
- "교대제 근무자 뇌출혈 산재 판례 중 공단 처분이 **취소**된 사건 보여 줘"
- "특수고용 기사의 근로자 여부가 쟁점이었던 심사청구에서 원처분이 **취소**된 결정서 보여 줘"
- "판정위 사건번호 240020210001716 판정서 전문 보여 줘"
- "이 문장이 판결문 원문과 똑같은지 확인해 줘: …"

| 자료 | 불복 단계 | 공공데이터포털 API | 건수(2026. 10. 기준) | 검색 방식 |
|---|---|---|---|---|
| 업무상질병 판정서 | 공단 판정 | [근로복지공단_질병판정서 조회 서비스](https://www.data.go.kr/data/15110836/openapi.do) | 약 6만 1천 건 | 공단 서버에서 실시간 검색 |
| 산재 심사결정서 | 심사청구 | [근로복지공단_심사결정서 조회 서비스](https://www.data.go.kr/data/15110818/openapi.do) | 3,000건 (2017년 무렵 사건 표본) | 공단 서버에서 실시간 검색 |
| 산재 판례 판결문 | 소송 | [근로복지공단_산재보험 판례 판결문 조회 서비스](https://www.data.go.kr/data/15041878/openapi.do) | 약 3만 5천 건 | 설치할 때 전체를 PC에 받아 두고 검색 (API에 검색어 기능이 없음) |

> 중간 단계인 **산재보험재심사위원회 재결**과 **행정심판 재결**은 이 MCP에 없습니다.
> [korean-law-mcp](https://github.com/chrisryugj/korean-law-mcp)처럼 법제처 자료를 다루는 MCP로 찾을 수 있습니다.

### 도구(기능) 목록

| 도구 | 하는 일 |
|---|---|
| `search_disease_rulings` | 질병판정서 검색 — 본문 검색어, 업종(산재보험 사업종류), 심의결과, 질병구분, 직종 |
| `get_disease_ruling` | 질병판정서 전문 보기 (한 번 검색해 본 판정서만 열 수 있음 — API에 사건번호 조회 기능이 없음) |
| `search_review_decisions` | 심사결정서 검색 — 본문 검색어, 사건명, 심사결과, 청구유형, 쟁점유형 |
| `get_review_decision` | 심사결정서 전문 보기 (한 번 검색해 본 결정서만) |
| `search_precedents` | 판례 검색 — 본문 검색어, 판결결과, 사건유형, 사고/질병 구분, 법원, 사건명 |
| `get_precedent` | 판결문 전문 보기 |
| `verify_quote` | 인용하려는 문장이 원문에 글자 그대로 있는지 대조 (띄어쓰기·줄바꿈 차이만 무시) |
| `list_codes` | 검색 조건에 넣을 분류 값과 건수 보기 |
| `update_precedents` | 판례 보관본을 **지금 바로** 다시 받기 (1~2분). 평소에는 [자동 갱신](#판례-자동-갱신)되므로 쓸 일이 거의 없음 |
| `precedent_update_log` | 판례 자동 갱신 기록(최근 30건)과 다음 확인 날짜 보기 |

### 검색어 쓰는 법

| 쓰는 법 | 뜻 | 예 |
|---|---|---|
| 낱말을 띄어 씀 | 모두 들어 있는 문서(AND) | `조리흄 폐암` |
| "따옴표" | 한 덩어리 구절 | `"업무상 재해"` |
| -낱말 | 그 낱말이 든 문서 제외 | `폐암 -흡연` |

## 자료의 한계 (꼭 읽어 주세요)

실제 데이터를 조회해 확인한 사항입니다.

- **날짜가 없습니다.** 판례에는 선고일, 판정서·심사결정서에는 결정일 칸이 없습니다. 서면에 날짜를 쓸 때는 따로 확인해야 합니다.
- **정신질환·자살 판정서는 사실상 공개되지 않았습니다.** 공개 판정서 중 정신질환 2건, 자해행위(자살 포함) 2건뿐입니다.
- **심사결정서는 2017년 무렵 사건 3,000건만 공개되어 있습니다.** 사건번호가 모두 2017로 시작합니다. 최근 경향으로 일반화하지 마세요.
  공개분의 심사결과는 기각 2,508건, 취소 361건, 일부취소 93건, 각하 37건, 취하 1건입니다.
- **판례 약 6,500건은 '취하' 사건**이라 판결문 본문이 없습니다.
- **판결결과는 공단 처분을 기준으로 적혀 있습니다.** 기각 = 대개 근로자 패소, 취소 = 대개 근로자 승소입니다.
- **판정서·심사결정서 검색은 띄어쓰기를 구분합니다.** "조리흄"과 "조리 흄"은 각각 찾아야 합니다. (판례 검색은 띄어쓰기를 무시합니다.)
- 판정서의 '업종'은 사업장 이름이 아니라 **산재보험 사업종류 이름**입니다. (예: 학교급식 → "국가 및 지방자치단체의 사업")
- 판정서·판결문의 개인정보는 공단이 ○○○ 등으로 가려 두었습니다.

## 설치 방법 (Windows) — Claude에게 맡기기

설치 파일을 실행하지 않습니다. **Claude Code**(Claude 데스크톱 앱의 Code 탭 또는 터미널의 `claude`)에게 설치를 맡깁니다.

### 1단계. 공공데이터포털 인증키 받기 (무료, 5분)

1. [공공데이터포털](https://www.data.go.kr)에 회원가입·로그인합니다.
2. 아래 세 페이지에서 각각 **[활용신청]** 을 누릅니다. 자동승인이라 바로 처리됩니다.
   - [근로복지공단_질병판정서 조회 서비스](https://www.data.go.kr/data/15110836/openapi.do)
   - [근로복지공단_심사결정서 조회 서비스](https://www.data.go.kr/data/15110818/openapi.do)
   - [근로복지공단_산재보험 판례 판결문 조회 서비스](https://www.data.go.kr/data/15041878/openapi.do)
3. **마이페이지 → 개발계정**에서 **일반 인증키(Decoding)** 를 확인해 둡니다. 세 API에 같은 키를 씁니다.

> 인증키는 본인 것만 쓰고 다른 사람과 나누지 마세요. 하루 호출 한도(API마다 10,000번)가 키마다 따로 계산됩니다.

### 2단계. Claude Code에 이 문장을 붙여넣기

```
https://github.com/cplalks-create/comwel-mcp 설치해 줘. 저장소의 INSTALL_FOR_CLAUDE.md 절차를 그대로 따라 줘.
```

Claude가 [설치 지침서](INSTALL_FOR_CLAUDE.md)를 읽고 아래 일을 순서대로 합니다. 중간에 허락을 구하는 창이 뜨면 확인하고 허용해 주세요.

- 프로그램 내려받기 (`C:\Users\내 이름\tools\comwel-mcp`)
- 파이썬 확인과 필요한 패키지 설치 (파이썬이 없으면 설치를 안내합니다)
- **인증키 입력창 띄우기** — 터미널에 뜨는 입력창에 1단계의 키를 붙여넣고 Enter. 입력한 글자는 `*`로 가려지고, 대화창에는 키가 남지 않습니다
  > 대화창에 키를 직접 붙여넣지 마세요.
- 판례 전체 내려받기 (1~2분, 약 500MB)
- Claude Code에 등록 (모든 폴더에서 사용)

### 3단계. 새 대화 열기

설치가 끝나면 **새 대화(새 세션)를 열어** 위 사용 예처럼 질문해 보세요.
Claude 데스크톱 앱의 **채팅**에서도 쓰고 싶으면 설치할 때 Claude에게 "채팅에서도 쓰게 해 줘"라고 하세요.

<details>
<summary>예비 방법: 설치 파일(install.bat)로 설치</summary>

Claude Code를 쓰지 않는 경우에만 씁니다. 이 페이지의 **[Code] → [Download ZIP]** 으로 받아 옮기지 않을 위치에 압축을 풀고,
`install.bat` 을 더블클릭합니다("Windows의 PC 보호" 창이 뜨면 [추가 정보] → [실행]).
인증키 입력 → 패키지 설치 → 판례 내려받기 → Claude 데스크톱 앱·Claude Code 등록까지 차례로 진행합니다. 끝나면 Claude를 완전히 종료했다가 다시 켭니다.
</details>

## 관리

모두 Claude Code에게 말로 맡길 수 있습니다.

| 하고 싶은 일 | Claude에게 이렇게 말하기 |
|---|---|
| **새 버전으로 업데이트** | "comwel 업데이트해 줘. https://github.com/cplalks-create/comwel-mcp 의 INSTALL_FOR_CLAUDE.md 업데이트 절차대로." (판례 보관본은 그대로 두고 프로그램만 바꿉니다. 새로 활용신청할 API가 있으면 알려 줍니다) |
| 판례를 최신으로 | **할 일 없음** — 자동으로 갱신됩니다(아래 [판례 자동 갱신](#판례-자동-갱신)). 지금 바로 받고 싶으면 "판례 보관본 지금 업데이트해 줘" |
| 갱신 기록 보기 | "판례 갱신 기록 보여 줘" |
| 인증키 바꾸기 | "comwel 인증키 바꾸고 싶어" (설치 폴더의 `scripts\set_key.ps1` 입력창을 띄워 줍니다) |
| 삭제 | "comwel 삭제해 줘" (지침서의 삭제 절차대로, 폴더 삭제 전에 확인을 받습니다) |

### 판례 자동 갱신

판례 API에는 날짜 칸이 없어서 새 판례만 골라 받을 수 없습니다. 그래서 Claude를 켤 때 뒤에서 아래처럼 확인합니다.

| 상황 | 하는 일 | 공단 서버 호출 |
|---|---|---|
| 마지막 확인 후 7일 이내 | 아무것도 하지 않음 | 0번 |
| 7일 지남 + 판례 건수 같음 | 확인만 하고 끝 | 1번 |
| 7일 지남 + 판례 건수 바뀜 | 전체를 다시 받음 (1~2분) | 약 35번 |
| 마지막으로 받은 지 30일 지남 | 건수가 같아도 다시 받음 (내용만 고쳐진 경우 대비) | 약 35번 |
| 공단 서버 오류 | 기존 보관본을 그대로 쓰고, 하루 뒤 다시 시도 | — |

- 받는 동안에도 검색은 기존 보관본으로 계속됩니다. Claude 창이 여러 개여도 한 곳에서만 받습니다.
- 받는 동안 임시 파일이 잠깐 약 500MB 더 생겼다가, 끝나면 정리됩니다.
- 검색 결과 아래에 "판례 보관본 기준: ○월 ○일"이 표시됩니다. 서면에 인용할 때는 원문을 확인한 날짜를 함께 남겨 두세요.
- 자동 갱신을 끄려면 사용자 환경변수 `COMWEL_AUTO_UPDATE` 를 `0` 으로 설정합니다.

## 문제 해결

| 증상 | 확인할 것 |
|---|---|
| 파이썬을 찾지 못함 | 파이썬 설치 때 "Add python.exe to PATH"를 체크했는지 확인하고, 다시 설치한 뒤 PC를 재시작 |
| "등록되지 않은 서비스키" 또는 [실패] 403 | 세 API 모두 활용신청을 했는지, **Decoding** 키를 넣었는지 확인. 신청 직후에는 반영까지 최대 1시간 걸릴 수 있음 |
| Claude에서 도구가 안 보임 | 새 대화(새 세션)를 열기. 데스크톱 앱 채팅이라면 앱을 트레이에서 완전히 종료한 뒤 다시 켜기 |
| "판례 보관본이 아직 없습니다" | Claude를 다시 켜면 자동으로 받습니다(1~2분). 바로 받으려면 Claude에게 "판례 보관본 지금 업데이트해 줘" |

## Mac·Linux (수동 설치)

```bash
python3 -m pip install -r requirements.txt
export DATA_GO_KR_KEY="발급받은 Decoding 키"
python3 src/check_key.py            # 키 확인
python3 src/sync_precedents.py      # 판례 내려받기
claude mcp add --scope user comwel --env DATA_GO_KR_KEY="발급받은 Decoding 키" -- python3 -X utf8 "$(pwd)/src/server.py"
```

Claude 데스크톱 앱은 `~/Library/Application Support/Claude/claude_desktop_config.json` 의 `mcpServers` 에
`"comwel": {"command": "python3", "args": ["-X", "utf8", "<폴더>/src/server.py"], "env": {"DATA_GO_KR_KEY": "<키>"}}` 를 추가합니다.

## 개발자용

```
INSTALL_FOR_CLAUDE.md       Claude Code가 따라 하는 설치·업데이트·삭제 지침서
scripts/set_key.ps1         인증키 가려진 입력창(사용자 환경변수 DATA_GO_KR_KEY에 저장)
install.bat / install.ps1   예비용 Windows 설치 파일
src/server.py               MCP 서버(도구 정의)
src/api_client.py           공단 API 호출 (인증키: 환경변수 → Windows 사용자 환경변수 순으로 읽음)
src/store.py                SQLite 보관본(판례 전체, 검색해 본 질병판정서·심사결정서)
src/search.py               검색어 해석·발췌·인용 대조
src/sync_precedents.py      판례 전체 내려받기
src/auto_update.py          판례 자동 갱신 확인(7일 건수 확인·30일 정기 갱신·잠금·기록)
src/check_key.py            인증키 확인
data/comwel.sqlite          보관본(저장소에는 올리지 않음)
```

```bash
py -m pip install -r requirements-dev.txt   # 개발용 패키지(pytest)
py -X utf8 -m pytest tests/ -v      # 단위 테스트(인터넷 불필요)
py -X utf8 tests/live_check.py      # 실제 서버·실제 MCP 연결 점검(인증키 필요)
```

## 변경 이력

| 날짜 | 내용 | 기존 사용자가 할 일 |
|---|---|---|
| 2026. 10. 30. | **설치 방식 변경** — 설치 파일 대신 Claude Code에 문장 하나를 붙여넣어 설치(INSTALL_FOR_CLAUDE.md). install.bat은 예비용으로 유지 | 할 일 없음 |
| 2026. 10. 30. | **판례 보관본 자동 갱신** — Claude를 켤 때 7일마다 건수 확인, 바뀌었으면(또는 30일마다) 뒤에서 다시 받음. 갱신 기록 도구 `precedent_update_log` 추가 | [새 버전으로 업데이트](#관리)만 하면 됨 |
| 2026. 10. 30. | **심사결정서(산재 심사청구) 검색 추가** — `search_review_decisions`, `get_review_decision` | 공공데이터포털에서 [심사결정서 조회 서비스](https://www.data.go.kr/data/15110818/openapi.do) **활용신청** 후 [새 버전으로 업데이트](#관리) |
| 2026. 10. 30. | 첫 공개 — 질병판정서·산재 판례 검색, 인용 대조, Windows 설치 파일 | — |

## 출처·라이선스

| 자료 (근로복지공단, 공공데이터포털) | 이용허락범위 |
|---|---|
| [질병판정서 조회 서비스](https://www.data.go.kr/data/15110836/openapi.do) | 제한 없음 |
| [심사결정서 조회 서비스](https://www.data.go.kr/data/15110818/openapi.do) | 제한 없음 |
| [산재보험 판례 판결문 조회 서비스](https://www.data.go.kr/data/15041878/openapi.do) | 공공누리 제1유형(출처표시) — 이 도구는 검색 결과마다 출처를 표시합니다 |

- 프로그램: [MIT License](LICENSE)