# Suicide Prevention Research MCP

국가건강검진의 **「기분상태 및 우울증」** 통계를 KOSIS Open API에서 조회하여  
Claude 등 MCP를 지원하는 LLM에서 활용할 수 있도록 만든 예제 MCP 서버입니다.

현재 예제는 다음 통계를 사용합니다.

- 자료명: 시도별 연령별 성별 일반건강검진 정신건강검사 결과 (기분상태 및 우울증)
- 제공기관: 국민건강보험공단
- 출처: KOSIS
- 통계표 ID: `DT_35007_N1180`
- 제공기간: 2018~2024년

---

## 주요 기능

현재 MCP는 다음 기능을 제공합니다.

### 1. 연도별 수검인원 조회

2018~2024년 국가건강검진 「기분상태 및 우울증」 수검인원을 조회합니다.

### 2. 중간정도 이상 우울증 의심 비율 계산

특정 연도, 성별, 연령대에 대해 다음 기준으로 비율을 계산합니다.

```text
중간정도 이상 우울증 의심
= 중간정도 우울증 의심 + 심한 우울증 의심
```

```text
비율
= 중간정도 이상 우울증 의심 인원
  / 전체 수검인원 × 100
```

### 3. 연령대별 추이 조회

20대~70대의 중간정도 이상 우울증 의심 비율을 연도별로 비교합니다.

---

## 프로젝트 구조

```text
suicide_mcp/
├── kosis.py
├── mcp_tools.py
├── server_stdio.py
├── server_http.py
├── requirements.txt
├── .env.example
└── README.md
```

- `kosis.py`  
  KOSIS Open API 조회 및 통계 계산

- `mcp_tools.py`  
  MCP Tool 정의

- `server_stdio.py`  
  Claude Code 등 로컬 MCP 클라이언트용

- `server_http.py`  
  Claude Web 등 원격 MCP 연결용

---

## 설치

Python 가상환경 사용을 권장합니다.

```bash
pip install -r requirements.txt
```

`requirements.txt` 예시:

```txt
requests>=2.31
python-dotenv>=1.0
mcp[cli]>=2,<3
```

---

## KOSIS API Key 설정

KOSIS Open API에서 API Key를 발급받아야 합니다.

`.env.example`

```env
KOSIS_API_KEY=your_kosis_api_key_here
```

이를 `.env`로 복사합니다.

```bash
cp .env.example .env
```

그리고 본인의 API Key를 입력합니다.

```env
KOSIS_API_KEY=발급받은_API_KEY
```

`.env` 파일은 GitHub에 업로드하지 않습니다.

`.gitignore`

```text
.env
__pycache__/
*.pyc
```

---

## 로컬 MCP 실행

Claude Code 등 로컬 MCP 클라이언트와 연결할 경우:

```bash
python server_stdio.py
```

`server_stdio.py`

```python
from mcp_tools import mcp

if __name__ == "__main__":
    mcp.run()
```

이 방식은 stdio transport를 사용합니다.

---

## HTTP MCP 실행

Claude Web 등 원격 MCP 연결을 위한 테스트:

```bash
python server_http.py
```

기본 주소:

```text
http://localhost:8000/mcp
```

`server_http.py`

```python
import os

from mcp_tools import mcp

if __name__ == "__main__":
    port = int(os.getenv("PORT", "8000"))

    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=port,
    )
```

---

## Render 배포

Claude Web에서 사용하려면 MCP 서버가 인터넷에서 접근 가능한 URL을 가져야 합니다.

Render와 같은 Python Web Service에 배포할 수 있습니다.

### Build Command

```bash
pip install -r requirements.txt
```

### Start Command

```bash
python server_http.py
```

Render 환경변수에 다음 값을 등록합니다.

```text
KOSIS_API_KEY=본인의_KOSIS_API_KEY
```

배포 후 예:

```text
https://suicide-mcp.onrender.com/mcp
```

이 URL을 Claude의 Custom Connector에 등록합니다.

---

## Claude Web 연결

Claude 웹사이트에서:

```text
Customize
→ Connectors
→ Add custom connector
```

MCP 서버 URL을 입력합니다.

예:

```text
https://suicide-mcp.onrender.com/mcp
```

이후 대화에서 해당 Connector를 활성화하면 Claude가 MCP Tool을 사용할 수 있습니다.

---

## 예시 질문

### 예시 1

```text
2018~2024년 국가건강검진
'기분상태 및 우울증' 수검인원 추이를 보여줘.
```

### 예시 2

```text
2024년 국가건강검진 '기분상태 및 우울증' 결과에서
20대 남성과 여성의 중간정도 이상 우울증 의심 비율을 비교해줘.
```

### 예시 3

```text
2018~2024년 연령대별 중간정도 이상 우울증 의심 비율의
변화를 비교하고 그래프로 보여줘.
```

---

## 응답 정보

MCP는 통계값뿐 아니라 다음 정보를 함께 제공하도록 구성합니다.

- 제공기관
- 출처
- 통계표 ID
- 제공기간
- 단위
- 계산 기준
- 그래프용 데이터
- 해석 시 주의사항

이를 통해 LLM이 임의의 통계를 생성하는 대신,  
지정된 공공 통계자료를 기반으로 답변하도록 하는 것이 목적입니다.

---

## 주의사항

본 프로젝트는 연구 및 MCP 활용 예제를 위한 것입니다.

국가건강검진 「기분상태 및 우울증」 결과는 선별검사 결과이며  
임상적 우울증 진단 또는 일반 인구의 우울증 유병률과 동일하게 해석해서는 안 됩니다.

또한 연도별 검사 대상 및 제도 변화에 따라  
연도 간 단순 비교에는 주의가 필요합니다.