MCP 클라이언트를 통해 자연어로 MIMIC-IV 의료 데이터를 쿼리하세요.

AI로 의료 데이터 분석을 혁신하세요! 평이한 영어로 MIMIC-IV 데이터에 대해 질문하고 즉각적인 통찰력을 얻으세요. 로컬 데모 데이터(무료) 또는 전체 클라우드 데이터셋(BigQuery) 중에서 선택할 수 있습니다.

• 🔍
  자연어 쿼리 (Natural Language Queries): 평이한 영어로 MIMIC-IV 데이터에 대해 질문하세요 - 🏠
  로컬 DuckDB + Parquet: DuckDB 뷰와 Parquet 파일을 사용하여 데모 및 전체 데이터셋에 대한 빠른 로컬 쿼리 제공 - ☁️
  BigQuery 지원: Google Cloud에서 전체 MIMIC-IV 데이터셋에 액세스 - 🔒
  엔터프라이즈 보안 (Enterprise Security): JWT 토큰을 사용한 OAuth2 인증 및 속도 제한 (rate limiting) - 🛡️
  SQL 인젝션 방지 (SQL Injection Protection): 포괄적인 검증을 거친 읽기 전용 쿼리

📺

비디오 튜토리얼을 선호하시나요? 설정, PhysioNet 구성 등을 다루는 단계별 비디오 가이드를 확인하세요.

우리는 MCP 서버를 실행하기 위해 uvx를 사용합니다.

공식 설치 프로그램을 통해 uv를 설치한 다음, uv --version으로 확인하세요.

macOS:

brew install uv

Linux (또는 Homebrew가 없는 macOS):

curl -LsSf https://astral.sh/uv/install.sh | sh
# macOS - Claude Desktop과 같은 GUI 앱을 위해 활성화:
sudo ln -s $(which uv) $(which uvx) /usr/local/bin/

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 확인:

uv --version

DuckDB 데모 데이터베이스를 사용하는 경우 이 단계를 건너뛰세요.

Google Cloud SDK 설치:

• macOS:
  brew install google-cloud-sdk

• Windows/Linux: https://cloud.google.com/sdk/docs/install

• macOS:

인증 (Authenticate):
gcloud auth application-default login

브라우저가 열립니다 - MIMIC-IV에 대한 BigQuery 액세스 권한이 있는 Google 계정을 선택하세요.

지원되는 클라이언트: Claude Desktop, Cursor, Goose 등.

|
m3 디렉토리를 생성하고 해당 디렉토리로 이동하려면 다음을 실행하세요: mkdir m3 && cd m3. 전체 데이터셋을 사용하려면 PhysioNet에서 수동으로 다운로드하여 다음 위치에 배치하세요: ```
uv init && uv add m3-mcp &&
uv run m3 init DATASET_NAME && uv run m3 config --quick

REPLACE
| 
GCP 자격 증명(credentials) 및 PhysioNet 액세스 권한이 필요합니다. 클라이언트 설정 JSON 파일에 다음을 붙여넣으세요: ```
{
"mcpServers": {
"m3": {
...

|

그게 전부입니다! MCP 클라이언트를 재시작하고 다음과 같이 질문해 보세요:

• "MIMIC-IV 데이터를 위해 어떤 도구들을 가지고 있나요?"
• "ICU(중환자실)의 환자 인구통계 정보를 보여줘"
• "입원 환자의 인종 분포는 어떻게 되나요?"

기능	DuckDB (데모)	DuckDB (전체)	BigQuery (전체)
비용	무료	무료	BigQuery 사용 요금
설정	설정 불필요 (Zero config)	수동 다운로드	GCP 자격 증명 필요
데이터 크기	환자 100명, 입원 275건	환자 365k, 입원 546k	환자 365k, 입원 546k
속도	빠름 (로컬)	빠름 (로컬)	네트워크 지연 (Network latency)
사용 사례	학습, 개발	연구 (로컬)	연구, 프로덕션

이미 Docker를 사용 중이거나 pip를 선호하시나요? m3를 실행하는 다른 방법은 다음과 같습니다:

|

git clone https://github.com/rafiattrach/m3.git && cd m3
docker build -t m3:lite --target lite .
docker run -d --name m3-server m3:lite tail -f /dev/null
``` |

git clone https://github.com/rafiattrach/m3.git && cd m3
docker build -t m3:bigquery --target bigquery .
docker run -d --name m3-server
...

**MCP 설정 (두 방식 모두 동일):**

{
"mcpServers": {
"m3": {
...

중지: `docker stop m3-server && docker rm m3-server`

`pip install m3-mcp`

💡

CLI 명령어: 사용 가능한 모든 옵션을 확인하려면 `m3 --help`를 실행하세요.

**유용한 CLI 명령어:**

`m3 init mimic-iv-demo`

- 데모 데이터베이스 다운로드
`m3 config`

- 대화형으로 MCP 설정 생성
`m3 config claude --backend bigquery --project-id YOUR_PROJECT_ID`

- 빠른 BigQuery 설정

**MCP 설정 예시:**

{
"mcpServers": {
"m3": {
...

기여자(Contributors)를 위한 안내:

기여자(Contributors)를 위한 안내:

git clone https://github.com/rafiattrach/m3.git && cd m3
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
...

**MCP 설정:**

{
"mcpServers": {
"m3": {
...

UV가 설치되어 있다고 가정합니다.

**1단계: 클론 및 이동 (Clone and Navigate)**

리포지토리 클론하기

git clone https://github.com/rafiattrach/m3.git
cd m3

**2단계: UV 가상 환경 생성 (Create UV Virtual Environment)**

가상 환경 생성

uv venv

**3단계: M3 설치 (Install M3)**

uv sync

이후 명령을 실행할 때는 반드시 uv run을 사용하여 uv 가상 환경을 사용하도록 하세요.

설치 후, 데이터 소스를 선택하세요:

**학습 및 개발에 완벽하며 - 완전히 무료입니다!**

-
**데모 데이터셋 초기화**: `m3 init mimic-iv-demo`

-
**MCP 클라이언트 설정**: `m3 config`

*대안: Claude Desktop 전용:* `m3 config claude --backend duckdb --db-path /Users/you/path/to/m3_data/databases/mimic_iv_demo.duckdb`

-
**MCP 클라이언트를 재시작하고 질문하기**: -

- 시스템에 따라 최대 30분이 소요될 수 있습니다 (예: MacBook Pro M3의 경우 10분)
- 성능 조절 옵션 (선택 사항):
충분한 메모리가 있는지 등 시스템 사양에 주의하세요.
export M3_CONVERT_MAX_WORKERS=6 # 병렬 파일 수 (기본값=4)
export M3_DUCKDB_MEM=4GB # 워커당 DuckDB 메모리 제한 (기본값=3GB)
export M3_DUCKDB_THREADS=4 # 워커당 DuckDB 스레드 수 (기본값=2)

-
**데이터셋 선택 및 확인**:`m3 use full # 선택 사항, m3 상태가 자동으로 full로 설정되었으므로 생략 가능`

- 상태(Status)는 활성 데이터셋, 로컬 DB 경로, Parquet 존재 여부, 빠른 행 수(row counts) 및 총 Parquet 크기를 출력합니다.

-
**MCP 클라이언트 설정** (전체 로컬 DB 사용):`m3 config # 또는 m3 config claude --backend duckdb --db-path /Users/you/path/to/m3/m3_data/databases/mimic_iv_full.duckdb`

**전체 MIMIC-IV 데이터가 필요한 연구자를 위한 안내**

- 결제(billing)가 활성화된 Google Cloud 계정 및 프로젝트
- BigQuery의 MIMIC-IV에 대한 액세스 권한 (PhysioNet 인증 필요)

-
**Google Cloud CLI 설치**
**macOS (Homebrew 사용):**
brew install google-cloud-sdk

**Windows:**
https://cloud.google.com/sdk/docs/install 에서 다운로드

**Linux:**
`curl https://sdk.cloud.google.com | bash`

-
**인증**:
gcloud auth application-default login

*브라우저가 열리면 MIMIC-IV 데이터가 포함된 BigQuery 프로젝트에 접근 권한이 있는 Google 계정을 선택하세요.*

-
**BigQuery용 MCP 클라이언트 설정**:
m3 config

*대안: Claude Desktop 전용 설정:* 
m3 config claude --backend bigquery --project-id YOUR_PROJECT_ID

-
**BigQuery 액세스 테스트**
- MCP 클라이언트를 재시작하고 질문하세요:
`Use the get_race_distribution function to show me the top 5 races in MIMIC-IV admissions.`

다른 MCP 클라이언트를 설정하거나 설정을 사용자 정의해야 하나요? 다음 명령어를 사용하세요:

`m3 config`

단계별 안내와 함께 모든 MCP 클라이언트에 대한 설정을 생성합니다.

기본값을 사용한 빠른 범용 설정

m3 config --quick

사용자 정의 DuckDB 데이터베이스를 사용한 범용 설정

...

의료 데이터에 대한 보안 액세스가 필요한 프로덕션 배포(Production deployments)의 경우:

Claude Desktop에서 OAuth2 활성화

m3 config claude --enable-oauth2
--oauth2-issuer https://your-auth-provider.com
...

**지원되는 OAuth2 제공업체 (Supported OAuth2 Providers):**

- Auth0, Google Identity Platform, Microsoft Azure AD, Keycloak
- 모든 OAuth2/OpenID Connect 준수 제공업체

**주요 이점 (Key Benefits):**

- 🔒 **JWT 토큰 검증 (JWT Token Validation)**: 업계 표준 보안 - 🎯
- **스코프 기반 액세스 (Scope-based Access)**: 세밀한 권한 제어 - 🛡️
- **속도 제한 (Rate Limiting)**: 오남용 방지 - 📊
- **감사 로그 (Audit Logging)**: 보안 모니터링

📖

전체 OAuth2 설정 가이드: 상세한 구성, 문제 해결 및 프로덕션 배포 가이드는 `docs/OAUTH2_AUTHENTICATION.md`를 참조하세요.

MCP 클라이언트가 질문을 처리할 때, 다음 도구들을 자동으로 사용합니다:

**get_database_schema**: 사용 가능한 모든 테이블 목록 조회
**get_table_info**: 테이블의 컬럼 정보 및 샘플 데이터 가져오기
**execute_mimic_query**: SQL SELECT 쿼리 실행
**get_icu_stays**: ICU 입원 정보 및 입원 기간(Length of stay) 데이터
**get_lab_results**: 실험실 검사 결과
**get_race_distribution**: 환자 인종 분포

MCP 클라이언트에게 다음과 같은 질문을 시도해 보세요:

**인구 통계 및 통계 (Demographics & Statistics):**

`Prompt:`

*MIMIC-IV 입원 데이터의 인종 분포는 어떻게 되나요?*

`Prompt:`

*ICU 입원 환자의 인구 통계 정보를 보여주세요.*

`Prompt:`

*데이터베이스에 총 입원 건수가 몇 건인가요?*

**임상 데이터 (Clinical Data):**

`Prompt:`

*환자 X의 실험실 검사 결과를 찾아주세요.*

`Prompt:`

*가장 흔하게 처방되는 실험실 검사는 무엇인가요?*

`Prompt:`

*최근 ICU 입원 사례를 보여주세요.*

**데이터 탐색 (Data Exploration):**

`Prompt:`

*데이터베이스에서 사용할 수 있는 테이블은 무엇인가요?*

`Prompt:`

*MIMIC-IV 데이터를 위해 어떤 도구들을 가지고 있나요?*

- Claude Desktop에서 모든 도구의 사용을 미리 승인하고 싶으신가요? 아래 프롬프트를 사용한 후 **Always Allow (항상 허용)**를 선택하세요.

`Prompt:`

*모든 도구를 논리적인 순서에 따라 호출해 줄 수 있나요?*

**로컬 "Parquet not found" 또는 보기 오류 발생 시:**
선택한 데이터셋에 대해 `m3 init` 명령어를 다시 실행하세요.

**MCP 클라이언트 서버가 시작되지 않는 경우:**

- MCP 클라이언트 로그를 확인하세요 (Claude Desktop의 경우: Help → View Logs)
- 설정 파일(configuration file)의 위치와 형식을 확인하세요
- MCP 클라이언트를 완전히 재시작하세요

**"Missing OAuth2 access token" 오류:**

액세스 토큰(access token) 설정

export M3_OAUTH2_TOKEN="Bearer your-access-token-here"

**"OAuth2 authentication failed" 오류:**

- 토큰이 만료되지 않았는지 확인하세요
- 토큰에 필요한 권한 범위(scopes)가 포함되어 있는지 확인하세요
- OAuth2 제공자(provider) 설정이 올바른지 확인하세요

**Rate limit exceeded (요청 제한 초과):**

- Rate limit 윈도우가 초기화될 때까지 기다리세요
- 필요한 경우 관리자에게 문의하여 제한(limits)을 조정하세요

🔧

OAuth2 문제 해결: 상세한 OAuth2 문제 해결 및 설정 가이드는 `OAUTH2_AUTHENTICATION.md`를 참조하세요.

**"Access Denied" 오류:**

- PhysioNet에서 MIMIC-IV 접근 권한이 있는지 확인하세요
- Google Cloud 프로젝트에서 BigQuery API가 활성화되어 있는지 확인하세요
- 인증 상태를 확인하세요:
`gcloud auth list`

**"Dataset not found" 오류:**

- 프로젝트 ID(project ID)가 올바른지 확인하세요
- `physionet-data` 프로젝트에 대한 접근 권한이 있는지 확인하세요

**인증(Authentication) 문제:**

재인증

gcloud auth application-default login

현재 인증 상태 확인

...

설정 지침은 위의 "Local Development" 섹션을 참조하세요.

pytest # 모든 테스트 (OAuth2 및 BigQuery 모의 객체(mocks) 포함)
pytest tests/test_mcp_server.py -v # MCP 서버 테스트
pytest tests/test_oauth2_auth.py -v # OAuth2 인증 테스트

환경 변수(environment variables) 설정

export M3_BACKEND=bigquery
export M3_PROJECT_ID=your-project-id
...

- 🏠
**Complete Local Full Dataset**: `mimic-iv-full`에 대한 지원 완료

(Download CLI) - 🔧
**Advanced Tools**: 더 전문화된 의료 데이터 기능

- 📊
**Visualization**: 내장된 플로팅(plotting) 및 차트 도구

- 🔐
**Enhanced Security**: 역할 기반 액세스 제어(Role-based access control), 감사 로깅(audit logging)

- 🌐
**Multi-tenant Support**: 조직 수준의 데이터 격리(data isolation)

MIMIC-IV 데모 데이터베이스가 사전 로드된 Docker 이미지를 사용하여 Kubernetes에 M3를 배포하세요:

Docker 이미지 빌드 및 푸시

make all # Docker 레지스트리/사용자 이름을 입력받습니다

또는 레지스트리를 직접 지정하세요

...

컨테이너는 3000번 포트에서 `/sse` 경로를 통해 StreamableHTTP 전송 (transport) 방식을 사용합니다.

클러스터 내부 접근(예: `http://m3.kagent.svc.cluster.local:3000/sse`)을 위해 서비스 엔드포인트에 연결하도록 MCP 클라이언트를 설정하세요.

M3 배포를 위한 Helm 차트는 별도의 리포지토리(repository)에서 사용할 수 있습니다.

여러분의 기여를 환영합니다! 다음 절차를 따라주세요:

- 리포지토리 포크 (Fork)
- 기능 브랜치 (feature branch) 생성
- 새로운 기능에 대한 테스트 추가
- 풀 리퀘스트 (pull request) 제출

연구에 M3를 사용하신다면, 다음을 인용해 주세요:

@article{attrach2025conversational,
title={Conversational LLMs Simplify Secure Clinical Data Access, Understanding, and Analysis},
author={Attrach, Rafi Al and Moreira, Pedro and Fani, Rajna and Umeton, Renato and Celi, Leo Anthony},
...

다른 형식의 인용이 필요한 경우 GitHub 페이지 상단의 "Cite this repository" 버튼을 사용할 수도 있습니다.

M3는 커뮤니티에 의해 포크(forked)되어 다음과 같이 변형되었습니다:

- MCPStack-MIMIC - M3를 다른 MCP 서버들(Jupyter, sklearn 등)과 통합합니다.

*의료 AI 커뮤니티를 위해 ❤️를 담아 제작되었습니다.*

**도움이 필요하신가요?** GitHub에 이슈(issue)를 생성하거나 위의 문제 해결 가이드를 확인하세요.