Garmin MCP Server

Garmin Connect の健康・ランニングデータをツールとして公開する MCP サーバーです。DeepSeek のようなLLMが、あなたのウォッチデータを毎日分析し、実際の数字に合わせて調整するランニング／ヘルスコーチとしてコーチングできるようになります。

Garmin watch ──sync──▶ Garmin Connect ──▶ garmin-mcp (this server)
                                                │  MCP tools (stdio / HTTP)
                                                ▼
                       DeepSeek (via scripts/deepseek_chat.py) or any MCP client
                       (Claude Desktop, Cherry Studio, Cursor, Claude Code, ...)

特徴

• 日次ヘルスダイジェスト — 1回の呼び出しで、睡眠（時間・スコア・段階）、安静時心拍数、HRV（就寝後＋週間）、ボディバッテリー、ストレス、SpO2、呼吸数、歩数、カロリー、運動強度分、朝のトレーニングレディネス、その日のワークアウトを返します。

• ランニングコーチ用データ — get_run_analysis は、期間内の総走行量、加重平均ペース、心拍数、カダンス、標高、トレーニング負荷、週次トレンドを集計します。get_activity_detail は、ラップごとのスプリットを詳細表示します。

• 18種類のツール — 日常の指標だけではなく、シリーズデータ、アクティビティだけでなく、トレーニング状況／レディネス、VO2max、レース予測、乳酸閾値、心拍数ゾーン、身体組成、自己ベスト、プロフィールをカバー。

• トークンベースの認証 — 一度ログイン（MFA対応）すれば、セッションはディスクに保存され、サーバーが自動的に切り替わるため、パスワード入力は不要です。

• モックモード — GARMIN_MOCK=true で決定的な合成データを提供することで、実際のアカウントを接続する前にパイプライン全体をテストできます。

• 組み込みDeepSeekブリッジ — scripts/deepseek_chat.py は DeepSeek に直接（function calling）でツールを提供し、対話形式または毎日実行用のワンショット形式で利用できます。

Related MCP server: Garmin Workouts MCP Server

要件

• Python 3.10+（3.13で開発）

• Garmin Connect アカウント（無料） 。二段階認証を有効にしたアカウントも対応しています。

セットアップ

cd /Users/jai/Documents/garmin_mcp_app

# 1. Create the virtualenv and install dependencies
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 2. Configure credentials
cp .env.example .env        # then edit .env: GARMIN_EMAIL, GARMIN_PASSWORD

一度ログインする（対話形式・MFA対応）

.venv/bin/python -m garmin_mcp.login_cli --verify

これにより Garmin Connect での認証が行われ、アカウントに2要素認証が設定されている場合はワンタイムコードの入力を求めてきます。その後、OAuthトークンは ~/.garminconnect（所有者のみ権限）に保存され、実際のデータをいくつか取得して動作確認を行います。以降、サーバーはパスワードを必要としません。

ログイン時のトラブル — Garmin がボット認証（captcha）を要求する場合があります。対策：ブラウザで一度 connect.garmin.com にログインしてから、ログインスクリプトを再実行してください。レート制限（429）を受けた場合は、数分待ってから再試みてください。

実際のアカウントなしでテストする（モックモード）

GARMIN_MOCK=true .venv/bin/python scripts/smoke_test.py

stdio上でサーバーを起動し、実際のMCPクライアントとしてあらゆるツールを実行します。19件の検証がすべて合成データで成功します。

MCPクラアンリに接続する

クライアントから起動スクユーザーを ./garmin-mcp-server（venv と PYTHONPATH を自動で解決）を指定してください。

Claude Deskt Desktop — claude_desktop_config.json に追加（また、config/claude_desktop_config.example.json の例を使用）。

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/jai/Documents/garmin_mcp_app/garmin-mcp-server",
      "type": "stdio"
    }
  }
}

Cherry Studio（DeepSeek対応デスクトップチャット）: Settings → MCP Servers → Add で、名前 garmin、タイプ stdio、コマンド /Users/jai/Documents/garmin_mcp_app/garmin-mcp-server を指定し、モデルに DeepSeek プロバイダーを選択してください。認証情報はプロジェクトの .env から取得するため、クライアント内で環境変数は不要です。

Claude Code / Cursor / Cline: mcp add garmin -- /Users/jai/Documents/garmin_mcp_app/garmin-mcp-server を実行します。

MCP Inspector（デバッグ用）: npx @modelcontextprotocol/inspector を実行し、上記のコマンドを指定して下さい。もしくはHTTPで実行 :

./garmin-mcp-server --transport streamable-http --port 8000

DeepSeek に直接接続する（任意のブリッジ）

DeepSeekのチャットAPIはOpenAI方式のfunction callingに対応しているため、このリポジトリにはGarminサーバーを起動し、そのツールをDeepSeekに直接渡して、何を取得するかを判断させる小さなブリッジが含まれています。

.venv/bin/pip install -r requirements-deepseek.txt   # adds 'openai'
# add DEEPSEEK_API_KEY to .env (see .env.example)

# interactive coach chat (uses prompts/coach.md as the system prompt)
.venv/bin/python scripts/deepseek_chat.py

# one-shot — cron-friendly ("daily analysis" job)
.venv/bin/python scripts/deepseek_chat.py --once "How was my recovery today? What should today's run be?"

独自のコーチングペルソナを prompts/coach.md に作成し、--system-prompt prompts/coach.md で渡してください（デフォルトです）。初期のプロンプトも同梱されています。

注意: DeepSeek の Web ／ チャット アプリ はMCP自体をサポートしていません。上記のブリッジがDeepSeekとこのサーバーを連携させる方法です。MCP対応のクライアント（Claude Desktop、Cherry Studio、Cursor、Claude Code、Claude Code）も、自前の DeepSeek APIT キーで機能します。

Webアプリ（ダッシュボード＋チャット）

.venv/bin/pip install -r requirements-web.txt    # fastapi + uvicorn
./garmin-web                                     # http://127.0.0.1:8080
./garmin-web --mock                              # try it with synthetic data
./garmin-web --port 9000                         # different port

以下が表示されます：

• 今日のカード — 睡眠スコア／時間、HRV、ボディバッテリー、安静時心拍数、ストレス、歩数／目標、トレーニング、ワークアウト。

• チャート（過去7日／14日／28日） — 安静時心拍数＋HRV、睡眠 、ボディバッテリー、歩数、週次ストレス、週間ランニング距離。

• 最近のランニング一覧 — 距離、ペース、心拍数、カダンス、標高、トレーニング効果、負荷。

• コーチチャットパネル — 自然言語で質問でき 。DeepSeek がリアルタイムの Garmin データを基に回答します（DEEPSEEK_API_KEY を .env に追加してください）。ダッシュボード自体はキーなしでも動作します。

Webアプリは Garmin サーバーへのMCPセッションを起動中ずっと保持し、他のクライアントと全く同じツール＆認証を使用します。チャートは Chart.js をCDNから読み込むため、ブラウザのインターネット接続が必要です。

使用できるツール

すべての出力は JSON 文字列です。成功時に {"ok": true, ...} が、それには {"ok": false, "error": ...} が返ります。日付は YYYY-MM-DD（ローカル時）です。

プロジェクト構成

src/garmin_mcp/
  server.py          MCP server (tools, transports, CLI)
  garmin_client.py   real Garmin Connect client (token resume, cache) + mock
  formatters.py      raw Garmin payloads → compact LLM-friendly JSON
  config.py          env / .env settings
  login_cli.py       one-time interactive login (MFA-capable)
  deepseek.py        shared DeepSeek ↔ MCP chat core (CLI + web app)
scripts/
  smoke_test.py      end-to-end MCP client test (mock by default)
  deepseek_chat.py   DeepSeek ↔ MCP bridge (interactive or --once)
  web_app.py         FastAPI backend for the web dashboard + chat
web/                 frontend (index.html, app.js, style.css)
garmin-mcp-server    executable launcher for MCP clients
garmin-web           executable launcher for the web app
config/              Claude Desktop config example
prompts/coach.md     your coach system prompt (edit me)

メモと注意事項

• これは Garmin の非公式（WEB）。 ／デバイス）エンドポイントをコミュニティ lイブラリ garmnconnect 経由で使用します。G乘以armin はこれらを随時に変更めきるため、フオマタは欠たフイールドがあっも動を的に調整めす。

• トークンファールは長期有今日のリフレッシュでトークンを格納しています。秘匿に保持してくなさい（~/.garminconnect 、パーミショ0600 で書き込ます）。

• サーバは GARMIN_CACHE_TLL 秒（デフォル600）間レスポンスをキャッし、LLMがする問いに重複た質問を投げなル時でGarminに過重をかけるを防ぎます。

• Webダッシュボードのチャートは Chart.js をCDN かわロードラるため、チャート表示にはインターネット接続を必要めします（カート付のテーブルはオフラインでも動作）。

• これは Garmin と関連しておらず、個人的に利用ます。

ラ イセンス

MIT