Elite MCP

自己ホスト型の Elite インスタンス（ワークアウト、食事、有酸素運動、体重を記録するパーソナルフィットネストラッカー）に対して、AI エージェントが直接リアルタイムに読み書きできるようにする MCP（Model Context Protocol）サーバーです。

このサーバーの使い方を判断するためにこのファイルを読んでいるエージェントへ：ツールを呼び出す前にファイル全体を読んでください。 各ツールの機能、引数の意味、期待される単位・形式、そして注意すべき点（主に：書き込みは即時かつ実際に反映され、取り消しはできません）を説明しています。以下の「データモデルに関する注意」と「安全に関する注意」のセクションは、ツール一覧と同じくらい重要です。

これは何か、何でないか

Elite（アプリ）はすべてのデータを独自の SQLite データベースに保存し、単純な REST API を通じて公開しています。ローカルキャッシュもオフラインキューもなく、単一の情報源です。この MCP サーバーは、その API に対する薄いプロトコルアダプターです。ここでの各ツール呼び出しは、指定された、すでに実行中の Elite インスタンスへの 1 回（または 2 回）の HTTP リクエストです。独自の状態は保持せず、キャッシュも行いません。get_workout_history を続けて 2 回呼び出すと、2 回とも新しい読み取り結果が得られます。

これは一般的なフィットネス API ではなく、他のアプリと通信することもなく、食品データベースの検索（OpenFoodFacts/USDA 検索）も行いません。その検索ロジックは Elite ウェブアプリ自体のクライアント側にあり、HTTP 経由では公開されていません。このユーザーのデータにまだない食品を記録する必要がある場合は、すでに知っているマクロまたはユーザーが提供するマクロを使って log_food を使用してください。ここには「食品を名前で検索する」ツールはありません。

要件

• URL がわかっている実行中の Elite インスタンス（例：http://192.168.1.50:8080、または自己ホストされている場所）。必要に応じて Elite リポジトリ を参照してセットアップしてください。

• Node.js 18 以上。

• その Elite インスタンスが API_TOKEN を設定して起動されている場合は、同じトークンが必要です。

セットアップ

git clone https://github.com/natyavidhan/elite-mcp.git
cd elite-mcp
npm install
cp .env.example .env   # then fill in ELITE_BASE_URL (and ELITE_API_TOKEN if the server needs one)

これは標準的な stdio MCP サーバーです。単独で実行して開いたままにするのではなく、MCP クライアントの設定によって起動されることを意図しています。エージェント/クライアントを node /path/to/elite-mcp/index.js に、環境変数として ELITE_BASE_URL（およびオプションで ELITE_API_TOKEN）を指定して向けてください。JSON 設定を読み取るクライアント（Claude Desktop、Claude Code、およびその他のほとんどはこの形式に従います）の場合：

{
  "mcpServers": {
    "elite": {
      "command": "node",
      "args": ["/path/to/elite-mcp/index.js"],
      "env": {
        "ELITE_BASE_URL": "http://192.168.1.50:8080",
        "ELITE_API_TOKEN": ""
      }
    }
  }
}

JSON 設定の MCP クライアントを持たないエージェントランタイム（カスタムオーケストレーターなど）の場合、同じ 2 つの環境変数と、stdio 経由で node index.js を起動することが契約全体です。index.js と src/client.js を参照してください。どちらも短いです。

ELITE_BASE_URL が設定されていない場合、プロセスは壊れた状態で起動するのではなく、stderr にエラーを記録してすぐに終了します。

ツール

合計 20 個のツール：接続確認 1 個、読み取り専用の分析ツール 11 個、ルックアップツール 1 個、書き込みツール 7 個。各ツールは結果を JSON テキストブロックとして返します。失敗（Elite に到達できない、トークンが不正、404、検証エラー）は、isError: true と {"error": "..."} の本文を持つ通常のツール結果として返されます。MCP 接続はクラッシュしないので、成功を前提にせず、それを確認してください。

接続

• check_connection — 引数なし。Elite の /api/health にアクセスします。他の何かが失敗している場合は、これを最初に呼び出してください。サーバーに到達できるかどうか、および AI コーチが有効かどうか（この MCP サーバーには関係ありませんが、正しいインスタンスと通信していることを示す有用なシグナルです）がわかります。

分析（読み取り専用）

これらは、Elite の組み込み AI コーチが内部的に呼び出すものとまったく同じです。同じ関数、同じ計算なので、数値は常にユーザーがアプリで見るものと一致します。

• get_workout_history({ days? }) — 過去 N 日間（デフォルト 30）のセッション：日付、エクササイズ、セット、総ボリューム。

• get_exercise_trend({ exerciseName, limit? }) — 1 つのエクササイズのセッションごとの最高重量の推移と、全期間の PR。exerciseName はあいまい一致（正確な ID、正確な名前、または部分文字列）で照合されます。トレンドを読むだけなら、最初に list_exercises を呼び出す必要はありません。

• get_personal_records({ limit? }) — エクササイズごとの最高重量と最高の単一セットボリュームを、重い順に表示。

• get_muscle_volume({ date }) — 特定の 1 日について、筋肉ごとのボリューム（主動筋はフルクレジット、補助筋は半分のクレジット）。

• get_weekly_muscle_summary({ days? }) — 過去 N 日間（デフォルト 7）の筋肉ごとの総ボリュームをランキング表示。これを使って、トレーニング不足の筋肉を見つけてください。

• get_muscle_exercise_split({ muscle, days? }) — 1 つの筋肉のボリュームを構成するエクササイズと、それぞれの割合（例：「私の上腕三頭筋の内訳は？」）。muscle は以下にリストされている列挙値のいずれかでなければなりません。

• get_food_log({ date }) — 1 日に記録されたすべてのエントリとマクロ、およびその日の合計。

• get_nutrition_trend({ days? }) — 過去 N 日間（デフォルト 7）の毎日のカロリー/マクロ合計と、ユーザーが設定した毎日の目標。

• get_cardio_summary({ days? }) — 過去 N 日間（デフォルト 30）の有酸素運動セッションと、個人ベスト。

• get_body_weight_trend({ days? }) — 過去 N 日間（デフォルト 90）のエントリと、現在値/開始値/変化/7 日平均。

• get_consistency({ days? }) — 過去 N 日間（デフォルト 14）について、ユーザーがワークアウト、食事、有酸素運動、体重を記録したかどうかを日ごとに表示。

ルックアップ

• list_exercises({ query? }) — 完全なエクササイズカタログ（組み込み + このインスタンスのカスタムエクササイズ）。オプションで、ID または名前に対する大文字小文字を区別しない部分文字列一致でフィルタリングできます。正確な exerciseId をすでに知らない場合は、log_workout_set の前にこれを呼び出してください — カタログは barbell_bench_press のような特定の ID を使用しており、自由テキストではありません。log_workout_set は実際の ID でないものを拒否します。

書き込み

ここでの書き込みはすべて、実行中の Elite インスタンスに即座に反映されます。実際のデータで使用する前に、以下の安全に関する注意を参照してください。

• log_workout_set({ date, exerciseId, reps, weightKg, rpe? }) — 1 セットを記録します。その日のワークアウトセッションがまだ存在しない場合は自動的に作成します。作成されたセットと isPR: true/false を返します。rpe（主観的運動強度、1〜10）はオプションです。

• delete_workout_set({ setId }) — 記録された 1 セットを削除します。

• delete_workout_session({ sessionId }) — セッション全体とその下のすべてのセットを削除します。確認手順はありません。このツールは、まさにそのとおりのことを行います。

• log_food({ date, mealType, name, quantityG, calories, protein?, carbs?, fat? }) — 食品エントリを記録します。マクロは quantityG の合計であり、100g あたりではありません（このツールが変換を行います）。背後で manual ソースの食品アイテムを作成します。

• delete_food_log({ logId }) — 記録された 1 つの食品エントリを削除します。

• log_cardio_session({ date, activityType, durationSeconds, distanceKm?, avgHeartRate?, caloriesBurned?, notes? }) — 有酸素運動セッションを記録します。

• log_body_weight({ date, weightKg, bodyFatPct?, notes? }) — 日付でアップサートします。すでにエントリがある日付に再度記録すると、重複を作成するのではなく上書きします。これは意図的であり（Elite アプリ自体の動作と同じ）、バグではありません。

データモデルに関する注意

• 日付は常に YYYY-MM-DD 形式の文字列で、時刻コンポーネントもタイムゾーンもありません。このサーバーには「今日」ヘルパーはありません。ユーザーが「これを今日の分として記録して」と言った場合は、ツールを呼び出す前に自分で今日の日付を解決してください。

• ID（sessionId、setId、logId、exerciseId など）は、Elite サーバー（またはエクササイズの場合はカタログで定義）によって生成される不透明な文字列です。決して構築したり推測したりしないでください。以前のツールの結果（log_workout_set の応答から実際の set.id と sessionId が得られます）または list_exercises から取得してください。

• muscle 列挙値（get_muscle_exercise_split 用）：chest、triceps、shoulder、lats、bicep、forearm、traps、quads、hamstrings、glutes、calves、abs。

• mealType：breakfast、lunch、dinner、snack。

• activityType：run、walk、cycle、swim、other。

• 重量はキログラム、距離はキロメートル、時間は秒です。ユーザーが Elite の UI をどの単位系で表示するように設定しているかに関係なく、常にこれらです。

安全に関する注意

• 取り消しはありません。 delete_workout_set、delete_workout_session、delete_food_log は、ユーザーの実際のトレーニング/栄養履歴に対する、実際の即時削除です。推測で、または「何が起こるか確認するためだけに」削除ツールを呼び出さないでください。ユーザーが明示的に削除を要求していない限り、最初にユーザーに確認してください。

• log_body_weight は、その日付の既存のエントリをエラーや確認なしに静かに上書きします。 ユーザーがすでに今日の体重を記録しているかどうか不明な場合は、最初に get_body_weight_trend を呼び出してください。

• このサーバーは、共有の ELITE_API_TOKEN（対象インスタンスが使用している場合）以外の認証を行いません。そのトークンが許可する範囲のアクセス権を持ち、デフォルトではすべてにアクセスできます。それに応じて扱ってください。

リポジトリ構成

index.js         entry point — starts the stdio MCP server
src/client.js     fetch wrapper around the target Elite instance's REST API
src/tools.js      every tool's schema + implementation

関連

• natyavidhan/elite — トラッカー自体。その README には、この MCP サーバーがツールとしてまだ公開していないものが必要な場合に備えて、このサーバーが基づいている完全な REST API（/api/data/*、/api/workout/*、/api/analytics/* など）が文書化されています。