에이전트 구성

출시된 Mac 앱에는 서명된 로컬 도우미 두 개가 포함되어 있습니다. 하나는 타입 지정 에이전트 도구용 healthmd-mcp이고, 다른 하나는 명시적인 CLI 워크플로용 healthmd입니다. iPhone 직접 연결 MCP를 지원하는 별도의 크로스 플랫폼 CLI는 명시적으로 검증되지 않은 공개 미리보기로 패키징되어 있습니다. 첫 안정판에는 실물 기기 출시 QA가 계속 필요합니다.

HealthKit은 iPhone에 그대로 유지됩니다.

구성을 마치면 로컬 클라이언트가 Health.md의 제한된 인터페이스에 접근할 수 있습니다. 컴퓨터나 에이전트에 HealthKit 직접 접근 권한을 부여하지 않으며, 소스 라이브러리를 Health.md 클라우드에 업로드하지도 않습니다.

인터페이스 선택

목표	시작 위치	다음 단계
Codex 또는 Claude가 Mac에서 건강 데이터를 조회하고 차트로 표시하도록 허용	stdio를 통한 번들 `healthmd-mcp`	MCP 서버 및 도구
Mac 스크립트에서 정규 JSON 또는 생성된 파일 내보내기	번들 `healthmd` CLI	CLI
Mac 앱 없이 열려 있는 iPhone에 직접 연결	이식 가능한 직접 연결 CLI(미리보기)	iPhone 직접 액세스
정확한 요청 및 응답 엔벨로프를 기준으로 개발	루프백 API 또는 공개 계약	루프백 API
스키마, 레코드, 증거 또는 생성된 픽스처 파싱	버전이 지정된 참조 문서	데이터 계약

백엔드와 전송 방식은 명시적으로 선택되며, Health.md는 iPhone 직접 접근에 실패해도 Mac 앱으로 암묵적으로 대체하지 않습니다.

Mac 앱에서 Codex 사용

현재 이용 가능 · 서명된 Mac 도우미

Mac용 Health.md를 설치하고 CLI 화면을 연 다음, 앱이 /Applications에 없다면 표시된 번들 MCP 경로를 복사하세요.

별도로 서명된 healthmd-mcp 도우미를 ~/.codex/config.toml에 추가하세요.

[mcp_servers.healthmd]
command = "/Applications/Health.md.app/Contents/Helpers/healthmd-mcp"
args = []
startup_timeout_sec = 10
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"

Codex를 다시 시작하고 healthmd_doctor를 호출한 다음 healthmd_metrics로 ID를 확인하세요. 업데이트 도구로 작은 범위를 명시적으로 가져온 뒤 healthmd_metric_chart 같은 타입 지정 도구로 그 범위를 조회하세요. 번들 서버는 Mac 준비 상태, 암호화된 컨텍스트 새로 고침 작업, 증거 및 시각화를 포함한 21개 도구를 제공합니다.

Mac에서 Claude Desktop 또는 Claude Code 사용

번들 도우미를 Claude Desktop의 MCP 구성이나 신뢰할 수 있는 Claude Code .mcp.json에 추가하세요.

{
  "mcpServers": {
    "healthmd": {
      "command": "/Applications/Health.md.app/Contents/Helpers/healthmd-mcp",
      "args": []
    }
  }
}

구성을 변경한 후 클라이언트를 다시 시작하세요. 프로젝트 범위 구성에도 작업 공간 신뢰와 명시적인 서버 승인이 필요합니다. 도구에 최신 HealthKit 데이터가 필요할 때는 Mac과 iPhone 앱을 모두 열어 두세요.

Mac의 모든 stdio MCP 클라이언트

하나의 로컬 프로세스를 구성하세요.

command: /Applications/Health.md.app/Contents/Helpers/healthmd-mcp
arguments: none
transport: stdio

호스트가 stdin과 프로세스 수명 주기를 관리합니다. 도우미를 일반적인 대화형 명령으로 실행하거나 JSON-RPC 출력을 변경하는 셸로 감싸지 마세요. MCP tools/list를 사용하여 설치된 앱이 제공하는 정확한 스키마를 확인하세요.

이식 가능한 직접 연결 설정

공개 미리보기 · 아직 안정판으로 검증되지 않음

크로스 플랫폼 Rust CLI, healthmd setup codex, 동일 바이너리의 healthmd mcp serve, Linux/Windows 직접 페어링은 명시적으로 검증되지 않은 공개 미리보기로 패키징되어 있습니다.

macOS 또는 Linux에서는 brew install CodyBontecou/tap/healthmd로 설치합니다. 이후 healthmd setup codex가 Codex를 멱등적으로 구성하고 iPhone 직접 페어링을 시작합니다. 릴리스 증거에 지정된 정확한 모바일 빌드를 사용하세요. 패키지 공개는 모바일 호환성의 증거가 아닙니다. iPhone 직접 연결 CLI 페이지에서 전송 및 프로토콜 동작을 설명합니다.

명시적인 CLI 워크플로

정규 추출 또는 파일 중심 자동화에는 MCP 호스트에 큰 소스 본문을 전달하도록 요청하는 대신 healthmd를 직접 호출하세요.

healthmd status
healthmd extract --category Sleep --last 7 --output sleep.json
healthmd export --last 7 --destination "$HOME/Documents/HealthVault"

번들 Mac 도우미와 독립 실행형 크로스 플랫폼 CLI는 이용 가능 여부와 문법이 서로 다릅니다. 명령을 무인 자동화에 복사하기 전에 Health.md CLI를 검토하세요.

이식 가능한 페어링 및 준비 상태

미리보기 · 이식 가능한 직접 연결 워크플로

다음은 현재 공개 패키지에 포함된 이식 가능한 워크플로입니다. 번들 Mac MCP 경로는 계속 Mac 앱의 기존 iPhone 연결을 사용합니다.

직접 MCP 및 CLI 워크플로를 사용하려면 iPhone의 Health.md와 신뢰할 수 있는 일회성 페어링을 완료해야 합니다. 페어링은 인증된 암호화 채널과 macOS, Linux 또는 Windows의 네이티브 자격 증명 저장소를 사용합니다.

iPhone의 Health.md에서 Direct CLI 액세스를 활성화하세요.
healthmd setup codex 또는 healthmd direct pair에서 페어링을 시작하세요.
iPhone에서 제한된 페어링 요청을 승인하세요.
쿼리 또는 내보내기를 시작하는 동안 Health.md를 포그라운드에 유지하세요.
더 큰 작업을 시작하기 전에 MCP에서 healthmd_doctor를 호출하거나 이식 가능한 CLI에서 healthmd status를 실행하세요.

수동 IP, Tailscale, 포트, 신뢰할 수 있는 기기, 포그라운드 실행 및 복구에 관한 자세한 내용은 iPhone 직접 액세스를 참조하세요.

구성 경계

로컬 에이전트 구성은 다음 권한을 부여하지 않습니다.

임의의 HealthKit 읽기 또는 쓰기
임의의 파일 시스템 접근
MCP를 통한 임의의 URL, 셸 명령, 프롬프트, 루트 또는 샘플링
누락 상태, 데이터 범위, 단위, 증거 또는 제한 사항을 숨길 권한
해당 승인을 받지 않고 생성된 파일 작업을 재개하거나 취소하거나 덮어쓸 권한

완전한 결과를 얻으려면 프로세스 성공 여부만 확인하지 말고 요청 범위, 데이터 범위, 순회, 제한 사항 및 소스 스키마를 검토하세요.