myfitnesspal-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working in this repository.

Project

mfp-mcp is an MCP server that reads and writes a MyFitnessPal account from any MCP client: search and log foods, weight, water, exercise, and the daily note, plus trends and exports from a local cache. It ships to PyPI as mfp-mcp and to the MCP Registry, and people run it against their real accounts.

MyFitnessPal has no public API. Every read and write replicates a request the MFP web app itself sends, over a curl_cffi session that impersonates Chrome so Cloudflare lets it through. When MFP changes its site, this project breaks, and most maintenance is keeping up with those changes.

Commands

Use uv for everything. uv.lock is gitignored, so don't commit one, and don't pip install into the project.

uv sync --extra autorefresh     # install, including the optional browser refresh
uv run pytest                   # tests: no network, no MFP account needed
uv run ruff check .             # lint (--fix applies safe fixes)
uv run ruff format --check .    # formatting (drop --check to apply)
uv run mfp-mcp auth             # connect a real account
uv run mfp-mcp                  # serve over stdio against that account

CI runs lint, pytest on Python 3.10 and 3.13, and a version-consistency check. Run pytest and both ruff commands before pushing.

Layout

The package is src/myfitnesspal_mcp/. A tool call flows top to bottom:

• server.py defines the MCP tools (fitness_*). It parses arguments, runs blocking work through with_session, and shapes the response. HTTP calls and SQL don't go here.
• food_logging.py owns the draft, confirm, and pin flow for logging food. food_ranking.py ranks candidates as pure functions.
• One module per MFP feature makes the web requests: diary.py (meals, entries, adding and removing food), food_search.py, measurements.py, water.py, notes.py, and exercise.py. Each function takes the client first. Request plumbing they share (URLs, headers, csrf pages, status checks) lives in mfp_web.py, and matching a query to logged entries, shared by food and exercise deletes, lives in entry_matching.py.
• mfp_client.py holds the curl_cffi client, the cached instance, and is_auth_error. auth.py captures and stores cookies, paste.py reads a pasted or copied cookie, session_persistence.py saves the cookies MFP re-issues back to cookies.json, refresh.py renews the session in a headless browser, and config.py reads env vars and paths.
• store.py is the local SQLite cache, and all SQL lives there. sync.py gap-fills the cache from MFP.