Quantified Self MCP Server

로컬 Model Context Protocol(MCP) 서버로, LLM(예: Claude Desktop)이 개인 건강 및 재무 데이터를 조회할 수 있게 해줍니다. 모든 데이터는 두 개의 로컬 SQLite 파일에 저장되며, 사용자가 제어하는 Python 프로세스가 디스크에서 직접 읽습니다. 클라우드 데이터베이스도, 대시보드도, 제3자 서비스도 없습니다.

포함 내용

quantified-self-mcp/
├── server.py              # the MCP server (FastMCP) — 2 tools
├── init_db.py              # loads a CSV file into the local SQLite database
├── requirements.txt
├── .gitignore              # keeps data/ and .db files out of version control
└── sample_data/
    ├── health_sample.csv   # 30 days of sample data, so you can try it immediately
    └── finance_sample.csv  # ~2 months of sample expenses

init_db.py를 실행하면 server.py 옆에 data/ 폴더가 생성되고 그 안에 health.db와 finance.db가 만들어집니다. 이 폴더는 사용자 자신의 데이터로 사용자 머신에서 생성되므로 여기에는 포함되지 않습니다.

Related MCP server: apple-health-mcp

노출되는 도구

두 도구 모두 일치하는 행 과 계산된 요약(건강 데이터의 평균/최소/최대, 재무 데이터의 카테고리별 합계)을 반환하므로, 모델이 여러 행에 걸쳐 직접 집계할 필요가 없습니다.

1. 환경 설정

Python 3.10+ 필요.

cd quantified-self-mcp
python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. 데이터 불러오기

포함된 샘플로 즉시 사용해 보세요:

python init_db.py health  sample_data/health_sample.csv
python init_db.py finance sample_data/finance_sample.csv

자신의 데이터를 사용하려면 다음 열로 CSV로 내보낸 후, 동일한 명령을 자신의 파일에 대해 실행하세요:

• health CSV: date, steps, sleep_hours, resting_heart_rate

• finance CSV: date, category, amount, description(description은 선택 사항)

날짜는 ISO 형식(2026-08-23)이어야 합니다. MM/DD/YYYY 형식도 허용되며 변환됩니다. 금액/숫자에는 $와 ,가 포함될 수 있으며(예: $1,234.56) 자동으로 제거됩니다. 문제가 있는 행(잘못된 날짜, 숫자가 아닌 금액, 누락된 카테고리 등)은 전체 가져오기를 중단하지 않고 경고와 함께 건너뜁니다. 마지막에 출력되는 줄에는 항상 로드된 행 수와 건너뛴 행 수가 표시됩니다.

init_db.py health를 다시 실행하면 날짜 기준으로 업서트(upsert)됩니다(날짜를 추가하면서 다시 실행해도 안전). init_db.py finance는 원장에 자연스러운 고유 키가 없으므로 매번 새 행을 추가합니다. 두 명령 모두에 --replace를 추가하면 먼저 테이블을 비우고 실행합니다.

3. (선택 사항) 단독 테스트

클라이언트에 연결하기 전에 MCP Inspector를 열고 브라우저에서 도구를 직접 호출할 수 있습니다:

fastmcp dev inspector server.py

4. Claude Desktop에 연결하기

Claude Desktop은 JSON 구성 파일을 기반으로 로컬 MCP 서버를 하위 프로세스로 실행하고 stdio를 통해 통신합니다:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

앱에서 바로 이동할 수 있습니다: Settings → Developer → Edit Config.

mcpServers 아래에 항목을 추가하되 절대 경로를 사용하세요. 중요한 점은 command를 단순한 python이 아니라 방금 만든 가상 환경 내부의 Python 인터프리터를 가리키게 해야 한다는 것입니다. Claude Desktop은 최소 환경에서 서버를 실행하므로 셸의 PATH나 활성화된 venv를 안정적으로 상속받지 못합니다. 따라서 단순한 "python"은 종종 잘못된 인터프리터(또는 아무것도)로 해석되어 서버가 조용히 시작에 실패합니다.

{
  "mcpServers": {
    "quantified-self": {
      "command": "/absolute/path/to/quantified-self-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/quantified-self-mcp/server.py"]
    }
  }
}

Windows에서는 일반적으로 다음과 같습니다:

{
  "mcpServers": {
    "quantified-self": {
      "command": "C:\\absolute\\path\\to\\quantified-self-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\absolute\\path\\to\\quantified-self-mcp\\server.py"]
    }
  }
}

파일을 저장한 후 Claude Desktop을 완전히 종료하고 다시 열어야 합니다(창을 닫는 것만으로는 부족합니다. 구성 변경을 로드하려면 재시작이 필요합니다). 채팅 상자에서 망치/도구 아이콘을 찾아 quantified-self가 연결되었는지 확인하세요.

FastMCP에는 이 파일을 편집해 주는 CLI 단축 명령도 포함되어 있습니다 — fastmcp install claude-desktop server.py --name "Quantified Self" — 시도해 볼 만합니다(현재 플래그는 fastmcp install claude-desktop --help 실행). 하지만 위의 수동 JSON 방식은 항상 작동하며 문제가 있을 때 디버깅하기 더 쉽습니다. Anthropic에는 로컬 MCP 서버용 최신 원클릭 "Desktop Extension" 패키징 형식도 있습니다. 이와 같은 개인 용도에는 필요하지 않지만, JSON 편집에 익숙하지 않은 사람과 이 서버를 공유하려는 경우 알아두면 유용합니다.

5. (선택 사항) Docker에서 실행 / Glama에서 호스팅

#5-optional-run-it-in-docker--host-it-on-glama

로컬 venv 대신 컨테이너에서 실행하려는 사람을 위해 Dockerfile이 포함되어 있습니다. 여기에는 Glama에서 호스팅하는 것도 포함됩니다. Glama는 저장소에 Dockerfile이 있으면 그 파일에서 직접 빌드합니다.

docker build -t quantified-self-mcp .
docker run -i --rm -v "$PWD/data:/app/data" quantified-self-mcp

이미지는 Python 전용입니다(python:3.12-slim + pip install -r requirements.txt). 이 프로젝트에는 Node.js가 전혀 없습니다. HEALTH_DB_PATH와 FINANCE_DB_PATH는 컨테이너 내부의 /data/health.db와 /data/finance.db를 기본값으로 사용하므로, 마운트된 볼륨(예: Glama의 /data 마운트)이 재배포 시에도 데이터베이스를 유지합니다. 재정의하려면 server.py 상단의 Configuration 섹션을 참조하세요.

glama.json은 의도적으로 최소한으로 유지됩니다. 단지 Glama가 이 저장소를 가리키게 할 뿐이며, 이미지가 어떻게 빌드되고 시작되는지(python server.py, stdio를 통해)에 대한 실제 정보는 Dockerfile이 담당합니다. 이전 버전의 glama.json은 Dockerfile을 사용하는 대신 일반 빌드팩(빈 debian:trixie-slim 베이스 이미지에 수동 pip install 빌드 단계와 cmdArguments 추가)을 수동으로 구성하려고 했습니다. 그 이미지에는 Python 인터프리터가 안정적으로 프로비저닝되지 않았고, 플랫폼은 이 저장소에 존재하지 않는 Node.js 엔트리포인트(Cannot find module '/app/server.js')를 실행하려고 시도했습니다. Dockerfile을 제공하면 이러한 모호성이 제거됩니다.

개인정보 보호 모델 — "로컬"이 실제로 의미하는 것

이 프로젝트의 핵심이므로 정확히 짚고 넘어가겠습니다:

• 두 SQLite 데이터베이스는 이 프로젝트의 data/ 폴더 안, 사용자 디스크에만 존재합니다. 서버는 네트워크 호출을 하지 않으며, 텔레메트리도 없고, 어디에도 동기화하지 않습니다.

• server.py는 두 데이터베이스를 SQLite의 읽기 전용 모드로 엽니다("쓰기를 실행하지 않는다"는 수준이 아니라 연결 자체가 물리적으로 쓸 수 없습니다). 버그가 있거나 악의적인 프롬프트라도 두 도구가 데이터를 수정할 수 없습니다. 터미널에서 사용자가 실행하는 init_db.py만이 데이터베이스에 쓸 수 있습니다.

• MCP 클라이언트가 이 도구 중 하나를 호출하면 해당 쿼리에 대해 반환된 특정 행이 응답하는 모델에 전송되는 대화의 일부가 됩니다. 이것이 MCP가 모델에 정보를 제공하는 메커니즘입니다. 호스팅된 모델과 함께 Claude Desktop을 사용하는 경우, 질문한 데이터 조각이 해당 턴에 Anthropic으로 전송된다는 뜻입니다. 채팅에 입력하는 다른 모든 내용과 마찬가지입니다.

• 따라서 여기서 "로컬"이 의미하는 바는: 전체 데이터셋이 제3자 데이터베이스에 저장되거나 동기화되지 않으며, 도구가 실제로 호출되지 않는 한 아무것도 전송되지 않는다는 것입니다. 그리고 그 경우에도 전체 데이터베이스가 아니라 해당 호출이 반환한 행만 전송됩니다. 완전한 오프라인 엔드투엔드를 의미하지는 않습니다. 그러려면 완전히 로컬인 모델 런타임(예: Ollama)과 MCP 호환 클라이언트가 필요합니다.

문제 해결

• Claude Desktop에 서버가 표시되지 않음: command와 args가 절대 경로를 사용하는지, venv의 Python 경로가 실제로 존재하는지, 앱을 완전히 종료하고 다시 열었는지 확인하세요. 로그는 ~/Library/Logs/Claude(macOS) 또는 %APPDATA%\Claude\logs(Windows)에 있습니다. mcp-server-quantified-self.log에 이 서버의 stderr가 표시됩니다.

• 도구에서 "No health/finance database found" 오류: 해당 데이터셋에 대해 먼저 init_db.py를 실행하세요. 도구는 의도적으로 빈 데이터베이스를 자동 생성하지 않으므로 조용히 빈 답변을 받지 않습니다.

• server.py 편집이 적용되지 않는 것 같음: Claude Desktop을 다시 시작하세요. 서버 프로세스는 메시지마다가 아니라 앱 세션당 한 번 시작됩니다.

• Glama 호스팅이 Cannot find module '/app/server.js' 오류로 실패: 배포가 Python 대신 Node.js 런타임으로 폴백되었음을 의미합니다. 이 저장소에는 server.js가 없습니다. 일반 빌드팩 구성 대신 포함된 Dockerfile(위의 "Docker에서 실행 / Glama에서 호스팅" 참조)로 빌드하여 플랫폼이 안정적으로 python server.py를 실행하게 하세요.

확장하기

원한다면 자연스러운 다음 단계 몇 가지를 소개합니다. 이 중 어느 것도 구현되어 있지 않으며, 단지 패턴이 이끄는 방향입니다:

• 항목을 CSV/SQL 대신 LLM을 통해 추가할 수 있도록 쓰기 도구(log_expense, log_daily_metric) 작성.

• 더 많은 지표 — 체중, 운동, 기분, 수분 섭취 — 각각은 또 다른 테이블과 또 다른 읽기 도구일 뿐입니다.

• read_finance_data 합계를 사용자가 정의한 목표와 비교하는 예산 대비 실적(budget-vs-actual) 도구.