fatsecret-mcp

fatsecret-mcp

スマートフォンでClaudeまたはChatGPTに話しかけて、FatSecretの日記に食事を記録できます。まず下書きが表示され、承認するまで保存されません。

https://github.com/user-attachments/assets/44dfd991-5434-47ad-8b84-bcad24415a1f

夕食の写真、Claudeが提案する下書き、「はい」という返事、その日の途中経過、FatSecretアプリに追加された新しい記録です。

fatsecret-mcpはセルフホスト可能なMCPサーバーです。Claude、またはOperatorで有効にした場合はChatGPTを、お使いのFatSecretの食事日記（FatSecretアプリで確認できる日記）に接続します。Claudeは、1日分または数週間分の記録を、1日のカロリーとマクロ栄養素の目標と照らし合わせて確認できます。FatSecretのカタログから食品を検索し、説明や写真をもとに記録の下書きを作成できます。各下書きには、分量、カロリー、マクロ栄養素、提案された食事区分、追加後の1日の状況が表示されます。カタログにない包装食品の場合は、栄養成分表示の写真だけで十分です。誤った記録も、同じように下書きを通じて修正または削除できます。

1つのサーバーを家庭で共有できます。複数の人がそれぞれ自分のFatSecretアカウントでサインインできます。公開インスタンスはないため、ご自身でサーバーを実行します。

このプロジェクトは非公式です。FatSecret、Anthropic、OpenAIとは提携しておらず、推奨も受けていません。また、医療や食事に関するアドバイスを提供するものではありません。

fatsecret Platform API を利用

できること

このサーバーはClaudeに5つのツールを提供します。ツールを自分で呼び出す必要はなく、話しかけるだけです。

search_foods

記録可能な分量とともに、カタログから食品を検索します。

あなた： 炊いたジャスミンライス1カップのカロリーはいくつですか？

Claude： FatSecretには「Jasmine Rice (cooked)」があります。1カップ（158 g）は205 kcal、タンパク質4.3 g、脂質0.4 g、炭水化物44.5 gです。

draft_entries

何も書き込まずに記録の下書きを提案します。

あなた： (皿の写真) これを昼食として記録して。

Claude： 今日の昼食の下書きはこちらです：

• 牛肉のビビンバ、1杯（480 g）：640 kcal、タンパク質32 g、脂質21 g、炭水化物80 g

レストランで出されるサイズの1杯と仮定しました。追加すると、2,200 kcal中1,420 kcal、タンパク質140 g中78 gになります。保存しますか？

confirm_draft

承認した下書きを書き込みます。

あなた： はい。

Claude： 保存しました。牛肉のビビンバを、FatSecretの日記の昼食に記録しました。

get_diary_day

1日分の記録を、合計と目標の残りとともに読み取ります。

あなた： 今日はあとどれくらいですか？

Claude： 1,420 kcalを摂取しています。残りは780 kcalで、タンパク質62 g、脂質18 g、炭水化物95 gです。

get_period_summary

最大31日分の日ごとの合計を読み取ります。

あなた： 先週と比べて、今週はどうでしたか？

Claude： 今週は1日平均2,050 kcal、タンパク質128 gでした。先週は1日平均2,240 kcal、タンパク質117 gでした。今週は2日、先週は4日、カロリー目標を超えました。

上記の数値は例です。

食事の記録方法

sequenceDiagram
    actor U as You (Claude app)
    participant C as Claude
    participant S as fatsecret-mcp
    participant F as FatSecret API
    U->>C: photo + "log this as lunch"
    C->>S: search_foods
    S->>F: foods.search, food.get
    C->>S: draft_entries
    S-->>C: draft (amounts, kcal, macros, meal, the day after adding)
    C-->>U: shows the draft
    U->>C: "yes"
    C->>S: confirm_draft(draft_id)
    S->>F: food_entry.create, one per item
    S-->>C: saved entries

下書きにはサーバーによる署名が付与され、30 分後に期限切れになります。作成対象となった本人だけが確認できます。Claude のコネクター設定では、confirm_draft を「承認が必要」に設定し、書き込みのたびに先に確認を求めるようにしてください。

カタログにない製品

無料の FatSecret API キーでアクセスできるのは、英語の米国カタログのみです。地元の商品やブランド製品のほとんどはカタログにありません。その場合、Claude は栄養成分表示の写真を求めるか、数値を入力するよう促します。サーバーは代替品として商品を記録します。カタログ内で最も近い食品を選び、表示のカロリーに合う量にして、製品本来の名前で記録します。

flowchart TD
    S[Claude searches the catalog] --> Q{Found?}
    Q -- yes --> E[Normal food entry]
    Q -- no --> P["You send a photo of the label<br/>or type its values"]
    P --> V[Claude reads the calories and macros]
    V --> M["The server picks the closest catalog food<br/>and sets the amount so calories match"]
    M --> N[Entry saved under the product's own name]

カロリーは表示と正確に一致しますが、マクロ栄養素は近似値にすぎず、かなりずれることもあります。これは、米国カタログにない製品を米国の製品に置き換えることによるものです。食事記録の項目には独自のカロリーやマクロ栄養素を設定できません。カタログ内の食品を参照し、その食品の値を使う仕組みです。無料のキーでは食品を作成できないため、サーバーは表示のマクロ栄養素に最も近い米国の食品を選びます。通常、製品の正確なマクロ栄養素は米国カタログのどこにもないため、これ以上近いものは選べません。確認前に、下書きには表示の値、記録される値、その差が示されます。FatSecret アプリで食事記録の項目の詳細を開くと、元になったカタログ食品を確認できます。

サーバーは、カロリーとマクロ栄養素がおおむね一致しない表示を拒否します。これにより、写真の読み取り間違いや、kJ を kcal と誤認したケースを検出します。代替品は記憶しません。次回は Claude が会話から表示を再利用するか、もう一度確認します。食事記録から代替品を繰り返す場合は、その名前と近似のマクロ栄養素が引き継がれます。

製品を頻繁に記録する場合は、FatSecret アプリで一度追加すれば、正確な値を使えるようになります。その後は、Claude が食事記録から再利用できます。

以前の食事を繰り返す

あなた： 昨日の朝食と同じもの。

Claude： 昨日の朝食は次のとおりです。

• ロールドオーツ、80 g：300 kcal
• 2％牛乳、250 ml：125 kcal
• ギリシャヨーグルト、150 g：90 kcal

今日もすべて同じですか。それとも、何かを省いたり量を変更したりしますか？

あなた： ヨーグルトなしで、牛乳は半分。

Claude： 昨日の内容を繰り返した下書きはこちらです。ロールドオーツ、80 g と 2％牛乳、125 ml で、合計 362 kcal です。今日の朝食として記録しますか？ その後、保存します。

Claude は過去の日の記録を読み取り、残す項目の下書きを作成します。カタログを検索する必要はありません。サーバーは食事記録から各項目の食品、分量、名前、栄養情報をコピーし、量を変更した場合はそれに応じて調整します。量は常にグラムまたは ml で表示されます。FatSecret アプリで追加したものなど、カタログから取得できない製品や、製品名が引き継がれて表示を再入力する必要のない代替品にも対応します。「2 枚」のようにグラムまたは ml で記録されていない量は、一度だけ検索してグラムで表示します。重量が不明な場合は、項目をそのまま繰り返します。

記録を修正または取り消す

あなた： (保存した直後に) 取り消して。

Claude： 下書きはこちらです。本日の昼食から牛肉ビビンバ、1 杯（480 g）、640 kcal を削除します。これで摂取量は 780 / 2,200 kcal になります。削除した記録は復元できず、再度記録する必要があります。削除しますか？

あなた： やっぱり残して。300 g だった。

Claude： 新しい下書きはこちらです。牛肉ビビンバ、1 杯（480 g）→ 300 g、640 → 400 kcal に変更します。昼食の範囲内です。この変更を保存しますか？

下書きでは、FatSecret アプリで記録したものも含め、日記にすでに記録されている項目も変更できます。グラムや ml 単位で量を変更したり、同じ日の別の食事に変更したり、名前を変更したりできます。削除も可能です。変更内容はそれぞれ、変更前と変更後の項目、および変更後の各日の状態とともに表示されます。「はい」と答えるまでは何も変更されません。「取り消して」と言うと、Claude は最後の保存で追加した項目を削除します。それ以外の場合は、まずその日を確認し、どの項目を指しているのか不明なときは質問します。

FatSecret では、項目を別の食品や別の日に移動できません。そのため、「鶏もも肉だった、むね肉じゃなくて」や「昨日のことだった」は、正しい項目を追加して、間違った項目を削除する1つの下書きになります。新しい項目が先に保存されるため、途中で何か失敗した場合は、記録が抜けるのではなく重複していることがわかります。変更は最長で1年前までさかのぼって反映されます。

できないこと

• バーコード、ポーランドのものなど地域別のカタログ、またはカスタム食品は検索できません。無料キーでアクセスできるのは米国のカタログのみのため、Claude は英語で検索します。記録は引き続き、使用した言語で入力した名前で保存され、食品が米国のカタログで照合されたことを示す「Kajzerka（米国カタログ）」のような短い注記が付きます。下書きにはカタログ上の名前も併記されます。
• 体重、運動、レシピは記録せず、食品の記録のみを扱います。
• 不特定の人には提供しません。公開サーバーはなく、各サーバーに登録できる人は固定されています。

自分で運用する

家庭用サーバーには、デプロイして他のメンバーを追加する管理者が1人います。家庭内の各メンバーは、管理者を通じて FatSecret に一度サインインした後、自分の Claude アカウントにカスタムコネクターとしてサーバーを追加します。管理者が有効にした場合は、ChatGPT に追加することもできます。

flowchart LR
    A["Anna's phone (Claude)"] --> CL[Claude connector]
    J["Jan's phone (Claude)"] --> CL
    CL -->|"each signs in with their own ID and password"| S[fatsecret-mcp on your server]
    O[Operator] -->|"add-user, check"| S
    S -->|"one FatSecret token per person"| F[FatSecret API]
    F --> D[("each person's own diary, the same as in the FatSecret app")]

必要なもの：

• 自分の FatSecret Platform API キー。platform.fatsecret.comで登録してください。無料の Basic プランで十分です。利用するには、FatSecret のAPI 規約に同意する必要があります。このプロジェクトにはキーは含まれていません。
• サーバー用の HTTPS 対応コンテナホスト（Railway など）。
• 各メンバー用の Claude または ChatGPT アカウント。プランでカスタムコネクターを利用できる必要があります。

簡単な手順：

1. FatSecret キーと署名キーを記載した .env を作成し、メンバーごとに uvx --env-file .env fatsecret-mcp add-user を一度実行します（セットアップ）。
2. それらの値を使って ghcr.io/jaronskijakub/fatsecret-mcp イメージをデプロイします（デプロイ）。
3. Claude で https://<your-server>/mcp をカスタムコネクターとして追加し、サインインします（コネクター）。

まず自分のコンピューターで試す場合は、Claude Code で stdio 経由で実行します。セットアップにもその方法が記載されています。リクエストのクォータ、間隔調整、キャッシュについては制限事項に、信頼モデルについてはSECURITY.mdに記載されています。

ChatGPT で使う

ChatGPT も Claude と同じ方法でサインインします。同じユーザー id とコネクターのパスワードを使い、同じ 5 つのツールを利用します。初期設定では無効です。運用者が FATSECRET_MCP_CLIENTS=claude,chatgpt を設定して再デプロイすると有効になります。

各ユーザーは ChatGPT でカスタムコネクターとして https://<your-server>/mcp を追加します。ChatGPT のカスタムコネクターは開発者モードで利用できますが、一部のプランに限られます。OpenAI の開発者モードの記事に対象プランが記載されています。両方のアプリを使う場合は、それぞれに個別にサインインします。サインアウトすると、両方の接続が終了します（コネクター）。このページの例は Claude から取得したものです。

ChatGPT では、追加は問題なく行える一方、変更や削除が確認済みでも、サーバーに届く前に「This tool call was blocked by OpenAI's safety checks」と表示されて処理が停止することがあります。その場合、日記は変更されません。新しいチャットで再試行するか、Claude または FatSecret アプリで変更してください。

ドキュメント

• セットアップ：設定、ユーザーの追加、各ユーザーの設定、Claude Code でのローカル実行について説明します。
• デプロイ：Railway、その他のコンテナホスト、Docker、および独自のイメージのビルドについて説明します。
• コネクター：Claude または ChatGPT へのサーバーの追加、サインイン、ユーザーのサインアウトについて説明します。
• 制限：1 日あたりのクォータ、リクエスト間隔、検索、下書き、入力サイズについて説明します。
• 変更履歴：各バージョンでの変更内容を記載しています。

脆弱性の報告は SECURITY.md からお願いします。信頼モデルと保存データの場所についても説明しています。

ロードマップ

• FatSecret Premier キーを持つユーザー向けのカスタム食品。代替品ではなく、正確な値でブランド商品を記録できるようにします。
• 米国のカタログにない商品を、名前またはバーコードで Open Food Facts から検索します。
• 自分の食品を名前で検索します。日記に記録したものは、記録した日から繰り返し記録できますが、よく記録する商品はまだ検索できません。日記全体から読み取るには API リクエストが多すぎるため、別の方法が必要です。
• ラベルから記録した商品を保存し、日記から繰り返し記録しない場合でも、代替品の登録に写真を再度使わなくて済むようにします。そのためには永続ストレージが必要です。
• 「はい」とチャットで入力する代わりに、下書き保存用のネイティブ確認ダイアログを Claude に追加します。

開発

uv sync
uv run ruff check && uv run ruff format --check
uv run pyright
uv run pytest

テストで FatSecret に接続することはありません。tests/fixtures/fatsecret/ に記録された応答を再生します。オプトインのスモークテストでは実際の日記を読み取ります：FATSECRET_LIVE_SMOKE=1 uv run --env-file .env pytest tests/test_live_smoke.py。コンテナのテストについてはデプロイを参照してください。

バージョンをリリースするには、uv version X.Y.Z を使ってバージョンを設定し、server.json の 2 か所にも設定して、日付付きの項目を CHANGELOG.md に追加します。tests/test_package.py で各所のバージョンが一致しているか確認します。そのコミットを main にプッシュし、イメージを公開する CI の完了を待ちます。その後、タグ vX.Y.Z をプッシュします。リリースワークフローでは、そのコミットについて main で CI が成功したことを確認し、パッケージをビルドして検証し、イメージにバージョンタグを追加し、パッケージを PyPI に公開して、変更履歴の項目から GitHub リリースを作成します。公開リポジトリでは、server.json も MCP レジストリに公開します。

ライセンス

MIT