FatSecret MCP Server

Model Context Protocol (MCP) server for the FatSecret Platform API. Search foods, read and manage your personal nutrition diary, saved meals, exercise, weight, favorites, recipes, and monthly summaries — all from any MCP-compatible client (ChatGPT Web, Claude Desktop, custom agents).

Features

39 tools total. Every mutating tool requires explicit user confirmation. Read-only tools work immediately.

Related MCP server: fitatu-wrapper

Quick Start

Prerequisites

• FatSecret Platform account with Consumer Key and Consumer Secret from FatSecret Platform

• Docker (recommended) or Python 3.11+

1. Configure credentials

cp .env.example .env
# Edit .env with your keys

Required variables:

FATSECRET_CONSUMER_KEY=your_consumer_key
FATSECRET_CONSUMER_SECRET=your_consumer_secret
MCP_AUTH_PASSWORD=your_strong_connection_password  # protects OAuth reconnect endpoint

Optional:

MCP_PUBLIC_URL=https://your-domain.com          # for OAuth callbacks
FATSECRET_REGION=ES
FATSECRET_LANGUAGE=es

2. Run with Docker (recommended)

docker compose up -d --build

Server listens on http://0.0.0.0:8000 with MCP endpoint at /mcp.

3. Authorize your personal FatSecret account

Open in browser:

https://your-domain.com/fatsecret/reconnect

Enter MCP_AUTH_PASSWORD, click Continue to FatSecret, log in and click Authorize. Done — your personal diary is now linked.

4. Connect from ChatGPT Web

1. Settings → Connectors → Add connector

2. Name: FatSecret

3. Description: Search foods and manage my personal FatSecret nutrition diary

4. Server URL: https://your-domain.com/mcp

5. Authentication: OAuth → check "I understand and want to continue"

6. Save

When prompted for the connection password, enter your MCP_AUTH_PASSWORD.

5. Connect from Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "fatsecret": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_AUTH_PASSWORD", "ghcr.io/yourname/fatsecret-mcp:latest"],
      "env": {
        "MCP_AUTH_PASSWORD": "your_password"
      }
    }
  }
}

Restart Claude Desktop.

Tool Examples

# Search foods (ES/es catalog by default)
await search_foods("pollo a la plancha", max_results=5)

# Get servings for a food_id
await get_food_servings("123456")

# List last 3 months of diary entries (default range)
await diary_entries_list()

# Custom date range
await diary_entries_list("2024-07-01", "2024-09-30")

# Add entry (after user confirms food, serving, quantity, meal, date)
await add_food_entry("123456", "Pollo a la plancha", "789", 1.5, "dinner", "2024-10-05")

# Copy today's lunch to tomorrow
await copy_food_diary("2024-10-05", "2024-10-06", "lunch")

# Get most-eaten foods at breakfast
await get_most_eaten("breakfast")

# Create a saved meal
await create_saved_meal_tool("Mi desayuno habitual", "breakfast,lunch", "Tostada + café + fruta")

# Add weight entry
await update_weight_entry(72.5, "2024-10-05", goal_weight_kg=70, current_height_cm=175)

# List exercise catalog
await list_exercises()

Architecture

• Transport: MCP Streamable HTTP (/mcp), stateless, JSON responses

• Auth: OAuth 2.1 server-side (protects MCP endpoints) + OAuth 1.0 3-legged to FatSecret Platform

• OAuth flow: HTTPS /fatsecret/reconnect → FatSecret authorization → /fatsecret/callback stores access token in Docker volume

• Data: no persistent storage except OAuth tokens; all calls hit FatSecret API live

• Rate limits: respects FatSecret limits with exponential backoff + Retry-After

• Region/Language: configurable via FATSECRET_REGION, FATSECRET_LANGUAGE (default ES/es)

Deployment

Generic Docker Compose (no hardcoded domains)

# docker-compose.yml
services:
  fatsecret-mcp:
    build: .
    container_name: fatsecret-mcp
    restart: unless-stopped
    env_file:
      - .env
    environment:
      MCP_HOST: 0.0.0.0
      MCP_PORT: "8000"
    ports:
      - "8000:8000"
    volumes:
      - fatsecret-data:/app/data

volumes:
  fatsecret-data:

Put behind any reverse proxy (Traefik, Nginx, Caddy) for HTTPS. Set MCP_PUBLIC_URL to your public URL for OAuth callbacks.

Environment Variables

Development

# Install with dev dependencies
pip install -e .[dev]

# Run tests
pytest -v

# Lint
ruff check src tests

# Type check
mypy src

# Run server locally
python -m fatsecret_mcp.server

Data Handling & FatSecret Terms

• No local caching of food/diary data beyond request lifetime

• OAuth tokens stored in Docker volume (fatsecret-data) for session persistence

• User data never leaves your infrastructure except to FatSecret API

• Respects FatSecret Platform Terms: no bulk export, no redistribution, no medical advice

• Delete tokens: docker volume rm fatsecret-data or use /fatsecret/reconnect to refresh

Contributing

See CONTRIBUTING.md.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.

Disclaimer

This is an independent integration. Not affiliated with FatSecret. API-created entries are verified only in FatSecret Platform API; consumer web/mobile app visibility depends on FatSecret's synchronization (not guaranteed).