guavahealth-fastmcp-app

Guava Health MCP is an open-source FastMCP server that wraps the Guava Health developer API and makes it available to MCP hosts like Cursor, Claude and ChatGPT. A hosted instance is reachable at https://guavahealth.fastmcp.app/mcp, and the project is MIT licensed. It is not affiliated with Guava Health, Inc. The server is read-only by design and does not persist health payloads; it proxies live Guava API reads after the user authorizes access. Version 0.1 exposes seven tools: guava_auth_status (whether Guava is connected for the current MCP user), guava_begin_connect (starts Guava OAuth with PAR and PKCE and returns an authorization_url), guava_disconnect (drops stored tokens for that user), guava_get_me (profile/subject), guava_search_sleep (sleep sessions), guava_search_activities (workouts and activities) and guava_search_metrics (metrics filtered by types such as steps or vo2_max). Writes are explicitly out of scope for this version. Architecture uses two OAuth layers. MCP client authentication runs through a GitHub OAuth App so hosts can connect securely and multiple users are supported. The Guava Health API side uses a confidential Guava API app with PAR, PKCE (S256) and refresh-token rotation. The documented flow is: MCP host authenticates via GitHub OAuth to guavahealth.fastmcp.app, which then talks to api.guavahealth.com over Guava OAuth 2.1. Setup requires registering a Guava API app at the Guava API portal with the exact redirect URI https://guavahealth.fastmcp.app/oauth/callback, enabling long-lived background access and the needed read scopes, then supplying GUAVA_CLIENT_ID and GUAVA_CLIENT_SECRET. A GitHub OAuth App is also needed, with homepage https://guavahealth.fastmcp.app and callback https://guavahealth.fastmcp.app/auth/callback, providing GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET. Environment variables include PUBLIC_BASE_URL, GUAVA_ENV (test or live), an optional GUAVA_API_BASE override, GUAVA_TOKEN_ENCRYPTION_KEY (a Fernet key for the token blob at rest), an optional MCP_AUTH_TOKEN shared bearer for automation, and an optional FASTMCP_JWT_SIGNING_KEY. The README shows how to generate a Fernet key with the cryptography package. Deployment notes mention a Horizon entrypoint of main.py (or main.py:mcp) and the MCP URL. For local use, the project uses uv: uv sync then uv run python main.py, serving at http://127.0.0.1:8000/mcp. Development commands are uv sync --group dev and uv run pytest -q. Security guidance in the README recommends minimum scopes and read-only tools first, never committing .env files, tokens or health API responses, encrypting the token store when GUAVA_TOKEN_ENCRYPTION_KEY is set, and re-connecting Guava after cold starts if Horizon disks are ephemeral. Logs redact client secrets where possible, and the README advises against dumping full API payloads into model context when a narrow answer suffices.