Hevy MCP (Remote)

hevy-mcp-remote：Hevy Fitness 向けのホスト型／ゲートウェイ対応 MCP

フォークに関するお知らせ。 これは、マルチテナント MCP ゲートウェイ向けに再パッケージされた、chrisdoc/hevy-mcp の独立してメンテナンスされているフォークです。同じ Hevy ツールを supergateway でラップし、標準入出力ではなく HTTP 経由で MCP ストリーム可能 HTTP を提供する OCI イメージとして公開しています。Claude Desktop、Cursor などでローカル／標準入出力用に利用する場合は、上流の hevy-mcp npm パッケージを使用してください。

Hevy フィットネストラッキングアプリ向けの Model Context Protocol（MCP）サーバーです。MCP ゲートウェイの背後でホストできるよう、supergateway でラップした OCI イメージとしてパッケージ化されています。/mcp で MCP ストリーム可能 HTTP を、/healthz でヘルスチェックを公開し、コンテナー環境から HEVY_API_KEY を読み込みます。

---

📋 目次

• 機能
• クイックスタート
• 前提条件
• インストール
  • Claude Desktop の設定
  • Cursor の設定
• hevy-mcp を選ぶ理由
• 設定
• 利用可能な MCP ツール
• 開発と貢献

---

🚀 機能

• ワークアウト管理：ワークアウトの取得、作成、更新ができます。
• ルーティン管理：ワークアウトのルーティンにアクセスして管理できます。
• エクササイズテンプレート：メモリー内キャッシュを使って、利用可能なエクササイズテンプレートを参照できます。
• フォルダー整理：ルーティンのフォルダーを管理できます。
• Webhook サブスクリプション：ワークアウトイベントの Webhook サブスクリプションを作成、表示、削除できます。

---

🏁 クイックスタート

お使いの環境に合ったワークフローを選択してください。

シナリオ	コマンド	要件
一時的な標準入出力での実行	HEVY_API_KEY=sk_live... npx -y hevy-mcp	Node.js ≥ 24、Hevy API キー
ローカル開発	npm install && npm run build && npm start	HEVY_API_KEY を設定した .env

---

🛠️ 前提条件

• Node.js：v24 以降（.nvmrc で固定されているバージョンを使用することを強く推奨します）。
• npm：v10 以降。
• Hevy API キー：すべての操作に必要です（Hevy PRO で利用できます）。

---

📦 インストール

npx 経由で実行（推奨）

リポジトリをクローンせずに、サーバーを直接起動できます。

HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp

手動インストール

# Clone the repository
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp

# Install dependencies
npm install

# Create .env and add your keys
cp .env.sample .env
# Edit .env and add your HEVY_API_KEY

---

🔗 統合

Claude Desktop の設定

このサーバーを Claude Desktop で使用するには、claude_desktop_config.json に以下を追加してください。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
	"mcpServers": {
		"hevy-mcp": {
			"command": "npx",
			"args": ["-y", "hevy-mcp"],
			"env": {
				"HEVY_API_KEY": "sk_live_your_key_here"
			}
		}
	}
}

Cursor の設定

~/.cursor/mcp.json の "mcpServers" にこのサーバーを追加してください。

{
	"mcpServers": {
		"hevy-mcp": {
			"command": "npx",
			"args": ["-y", "hevy-mcp"],
			"env": {
				"HEVY_API_KEY": "your-api-key-here"
			}
		}
	}
}

---

✨ hevy-mcp を選ぶ理由

• 🚀 高パフォーマンス：Oxc ツールチェーン（oxlint／oxfmt）を使用して構築されており、ほぼ瞬時に lint とフォーマットを実行できます。
• 🛡️ 型安全性：Zod と Kubb で生成された API クライアントを使用した、完全な型安全性を備えています。
• 📉 可観測性：エラー追跡とパフォーマンスプロファイリングのための Sentry モニタリングを内蔵しています。
• ⚡ 最適化：エクササイズテンプレートをメモリー内にキャッシュし、API のレイテンシーを低減します。

---

⚙️ 設定

Hevy API キーは次の方法で指定します。

1. 環境変数：HEVY_API_KEY（.env またはシステム環境変数）。
2. CLI 引数：--hevy-api-key=your_key（npm スクリプト内で -- の後に指定）。

# Example .env
HEVY_API_KEY=your_hevy_api_key_here

📡 Sentry の監視

hevy-mcp には、本番環境でエラーと使用状況を監視するための Sentry モニタリングが含まれています。トレーシングを有効にし、個人を特定できる情報の収集をデフォルトで無効にして、@sentry/node を初期化します。

---

🐳 MCP ゲートウェイの背後で実行する（supergateway コントラクト）

MCP サーバー自体が使用する通信方式は stdio のみです。マルチテナントのゲートウェイ環境（例：mcp-gateway-poc）向けに、このリポジトリには、stdio バイナリを supergateway でラップし、1 つのコンテナで MCP のストリーミング可能な HTTP を公開する Dockerfile が用意されています。

このイメージは、ゲートウェイ上でホストされるすべての MCP が従う、次のコントラクトに準拠しています。

• 0.0.0.0:$PORT の /mcp で MCP のストリーミング可能な HTTP を提供
• /healthz にヘルスエンドポイントを提供
• ステートフルなセッション（Mcp-Session-Id に対応）
• HEVY_API_KEY をコンテナ環境から読み取り、起動する stdio 子プロセスに渡す

イメージは main および手動で作成したすべての GitHub リリースから、ghcr.io/rwestergren/hevy-mcp に公開されます。ローカルでのビルド方法：

docker build -t hevy-mcp:local .
docker run --rm -e HEVY_API_KEY=sk_live_... -p 8080:8080 hevy-mcp:local
curl http://localhost:8080/healthz

hevy-mcp を直接実行するエンドユーザーは、上記の stdio／npx の手順を使用してください。Docker イメージは個々のクライアントではなく、ゲートウェイの運用者を対象としています。

---

🛠️ 利用可能な MCP ツール

カテゴリ	ツール
ワークアウト	get-workouts、get-workout、create-workout、update-workout、get-workout-count、get-workout-events
ルーティン	get-routines、get-routine-by-id、create-routine、update-routine
テンプレート	get-exercise-templates、get-exercise-template、search-exercise-templates
フォルダー	get-routine-folders、get-routine-folder、create-routine-folder
Webhook	get-webhook-subscription、create-webhook-subscription、delete-webhook-subscription

---

👨‍💻 開発とコントリビュート

クイックコマンド

• ビルド：npm run build
• Lint／フォーマット：npm run check（oxlint／oxfmt を使用）
• ユニットテスト：npx vitest run --exclude tests/integration/**
• 全テストスイート：npm test（HEVY_API_KEY が必要）

シニアエンジニア向けの詳細なガイドについては、AGENTS.md を参照してください。

API クライアントの生成

API クライアントは、Kubb を使用して OpenAPI 仕様から自動生成されます。

npm run build:client

---

📄 ライセンスと謝辞

• ライセンス：MIT
• クレジット：Model Context Protocol、Hevy Fitness。

---

コントリビュートを歓迎します！ 大きな変更については、Issue または PR を作成してください。