hevy-mcp

ClaudeをHevyのワークアウトログに接続します。

hevy-mcpは、Model Context Protocolサーバーです。これを使用すると、Claude（デスクトップ版またはclaude.ai）でワークアウトの読み取り、新しいルーチンの設計、Hevyライブラリへの保存、トレーニング傾向の分析が可能になります。これは、ChatGPTユーザーがHevyの公式統合で利用できるものと同等のアクセス権を提供します。

You: "Build me a 4-day upper/lower hypertrophy split focused on the muscle groups
      I've trained least over the last 30 days, and save it in a folder called
      'Hypertrophy Block 1'."

Claude: ✓ checked your last 30 days of training (lats and rear delts are behind)
        ✓ created folder "Hypertrophy Block 1"
        ✓ resolved 22 exercises against Hevy's library
        ✓ saved 4 routines: Upper A, Lower A, Upper B, Lower B
        Open the Hevy app to start any of them.

Claudeに依頼できること

• 振り返り — 「過去10回のワークアウトを表示して、おろそかにしている筋肉グループを教えて。」

• 計画 — 「ベンチプレスの履歴に基づいて、明日のトップセットの適切な重量は？」

• ルーチン作成 — 「4日間の上半身/下半身の筋肥大スプリットを作成して保存して。」

• ルーチン編集 — 「『プッシュデイA』のダンベルショルダープレスを、バーベルオーバーヘッドプレス（5回×4セット）に変更して。」

• 分析 — 「主要なリフトの1RMを推定し、過去90日間のスクワットの進捗をグラフ化して。」

要件

• Hevy PROサブスクリプション（開発者APIの利用に必要です）。

• Hevy APIキー — https://hevy.com/settings?developerで取得してください。

• Python 3.11+ または Docker。

• Claude Desktop、またはカスタムコネクタをサポートするclaude.aiワークスペース。

クイックスタート — Claude Desktop (5分)

1. インストール

# Easiest, with uv (https://docs.astral.sh/uv/):
uv tool install hevy-mcp

# Or with pipx:
pipx install hevy-mcp

# Or with plain pip:
python -m pip install hevy-mcp

2. Claude Desktopへの追加

Claude Desktopの設定ファイルを開きます：

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

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

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

mcpServersの下にhevyエントリを追加します（ファイルが存在しない場合は作成してください）：

{
  "mcpServers": {
    "hevy": {
      "command": "hevy-mcp",
      "env": {
        "HEVY_API_KEY": "sk_live_paste_your_key_here"
      }
    }
  }
}

hevy-mcpがPATH上にない場合（uv-toolのインストールがClaude Desktopランチャーで認識されないことがあります）、which hevy-mcpで取得できる絶対パスを使用してください（例: /Users/you/.local/bin/hevy-mcp）。

3. Claude Desktopの再起動

完全に終了（macOSでは⌘Q）してから再起動します。ツールインジケーターが表示され、hevyサーバーが接続されていることが確認できるはずです。

4. 試してみる

「hevyツールを使って、過去3回のワークアウトを取得して要約して。」

Claudeが実際のワークアウトを表示すれば完了です。🎉

代替手段 — claude.ai (リモートコネクタ)

Claude Desktopではなくブラウザでclaude.aiを使用している場合は、hevy-mcpをHTTPサービスとして実行し、カスタムコネクタとして追加します。

1. HTTPS環境でサーバーを実行する

最も簡単な方法は、Fly.io / Render / RailwayでDockerを使用することです：

docker build -t hevy-mcp .
docker run --rm -p 8000:8000 -e HEVY_API_KEY=sk_live_... hevy-mcp

またはCLIで直接実行します：

hevy-mcp --http --host 0.0.0.0 --port 8000

MCPエンドポイントは/mcpにあります。

2. カスタムコネクタとして追加する

claude.aiで、設定 → コネクタ → カスタムコネクタを追加に移動し、/mcpで終わるパブリックHTTPS URL（例: https://hevy-mcp.fly.dev/mcp）を使用します。

マルチユーザーに関する注意

複数のユーザーが同じデプロイメントを共有する場合は、HEVY_API_KEYをコンテナの環境変数に埋め込まないでください。代わりに、リクエストごとのヘッダーとして送信してください。サーバーはX-Hevy-Api-Keyが存在すればそれを読み取り、なければ環境変数にフォールバックします。サーバーの前に認証を注入する小さなリバースプロキシ（Cloudflare Worker、Nginxなど）を配置するのが一般的なパターンです。

機能一覧 (全ツールリスト)

内部構造:

• スマートキャッシング — エクササイズライブラリは一度取得されると24時間キャッシュされ、あいまい検索はメモリ上で実行されます。

• レート制限対応 — 429エラー時にバックオフし、Retry-Afterを尊重します。

• べき等な書き込み — 同じフォルダ内に重複するタイトルのルーチンを作成する場合、Claudeに確認を求めます。

• LLMフレンドリーなエラー — すべてのエラーは { error, hint } として返されます。ヒントには次の具体的なツール呼び出しが提案されます。

• APIキーのログ記録なし — APIキーをログに記録することはありません。

トラブルシューティング

最も一般的な原因は、claude_desktop_config.jsonのcommandがランチャーのPATH上にないことです。"command": "hevy-mcp"をwhich hevy-mcp（Windowsの場合はwhere hevy-mcp）で取得した絶対パスに置き換えてください。その後、Claude Desktopを再起動してください。

• キーがargsブロックではなくenvブロックに貼り付けられているか確認してください。

• Hevy PROサブスクリプションが有効であることを確認してください。

• https://hevy.com/settings?developer でキーを再生成して試してください。

search_exercise_templatesはあいまい検索ですが、完璧ではありません。Claudeが間違ったエクササイズを選択した場合は、「より具体的な名前で再検索して」と指示するか、equipmentフィルター（例: "barbell"）を渡すようにしてください。

エクササイズライブラリは最初の検索時に取得されます（初回のみ約200ms）。それ以降の呼び出しはメモリ内のキャッシュにヒットします。キャッシュは24時間有効です。

開発

git clone https://github.com/Vellarasan/hevy-mcp.git
cd hevy-mcp
uv sync --extra dev          # creates .venv and installs deps
pytest -q                    # offline tests (no real API needed)

# Run against your real Hevy account:
HEVY_API_KEY=sk_live_... python smoke_test.py

# Stdio (Claude Desktop):
hevy-mcp

# HTTP (claude.ai):
hevy-mcp --http --port 8000

詳細は CONTRIBUTING.md を参照してください。

プロジェクト構成

hevy-mcp/
├── src/hevy_mcp/
│   ├── server.py        # transport bootstrap (stdio + streamable-http)
│   ├── hevy_client.py   # async httpx client w/ retries & error mapping
│   ├── schemas.py       # Pydantic models
│   ├── cache.py         # 24-hour TTL cache
│   ├── errors.py        # HevyApiError + tool_guard
│   ├── formatters.py    # JSON → readable text
│   └── tools/           # workouts, routines, folders, templates, webhooks, analytics
├── tests/
└── Dockerfile

リリース

CHANGELOG.md を参照してください。タグ付けされたリリースは自動的にPyPIに公開されます。

ライセンス

MIT。

謝辞

このプロジェクトの設計は、コミュニティによる2つの先行実装 chrisdoc/hevy-mcp (TypeScript) と SrdjanCodes/hevy-mcp (Python) から着想を得ています。フォークではありませんが、異なる言語や機能セットが必要な場合は一見の価値があります。

hevy-mcpはコミュニティプロジェクトであり、Hevyとは提携しておらず、Hevyによって承認されたものでもありません。