AI Assistant & MCP Server

SparkyFitness includes a powerful Model Context Protocol (MCP) server. This allows you to connect advanced AI assistants (like Claude Desktop, Cursor, or custom AI clients) directly to your personal health data securely.

When you enable the MCP Server, your AI assistant transforms into a Personal Health Intelligence layer that can read your health logs, track your progress, and provide hyper-personalized coaching based on your actual data.

---

🛠 Available Tools & Capabilities

The AI assistant can perform the following actions across different health domains. All tools automatically respect your Unit Preferences (e.g., converting lbs to kg or kcal to kJ).

🥗 Nutrition & Food

Track your diet, manage meals, and analyze your nutritional intake.

Feature	Tool Action	Example Prompt
Log Food	log_food	"I just had a 250g steak and a salad."
Quick Add	log_external_food / create_food	"Quick add my restaurant tasting menu, ~1200 kcal — don't save it to my foods."
Meal Templates	log_meal	"Log my 'Standard Breakfast' for today."
Water Tracking	log_water	"I drank 500ml of water."
Daily Diary	list_diary	"What have I eaten today?"
Copy Entries	copy_from_yesterday	"Copy my breakfast from yesterday to today."
Nutrition Analysis	get_nutritional_summary	"Give me a breakdown of my macros for the last 7 days."

INFO

Quick Add mirrors the checkbox in the web and mobile food forms: the food is logged to your diary for that date but stays out of your food list, search, favorites, and recents. It applies to whichever path the assistant already uses — log_external_food for a match from a provider such as OpenFoodFacts or USDA, create_food for a custom or homemade food — so asking for Quick Add never costs you the verified provider nutrition. It applies only to foods being added for the first time: if the food is already in your food list, it stays there and the assistant tells you Quick Add was not applied, because hiding it would remove a food you already rely on. Ask for it explicitly ("quick add", "don't save this to my foods"); otherwise foods the assistant creates are saved to your list as usual.

🏋️ Exercise & Fitness

Manage your workouts, track strength progress, and use presets.

Feature	Tool Action	Example Prompt
Log Workout	log_exercise	"Log 3 sets of Bench Press at 80kg for 10 reps."
Workout Presets	log_workout_preset	"Start my 'Leg Day' workout."
Exercise Details	get_exercise_details	"How do I perform a Bulgarian Split Squat?"
Progress Tracking	get_exercise_progress	"Show me my Bench Press progress over the last month."
Search Library	search_exercises	"Find some advanced chest exercises using dumbbells."
Alternatives	suggest_alternatives	"What can I do instead of bench press? Only dumbbells."
Rate a Workout	rate_workout	"Yesterday's workout felt too hard; my knee hurt."
Adaptive Coaching	get_workout_coaching	"Will my Push Day change next time, and why?"

📈 Biometrics & Check-ins

Monitor your weight, sleep, mood, and daily habits.

Feature	Tool Action	Example Prompt
Daily Wizard	sparky_daily_checkin_wizard	"I'm ready for my daily check-in."
Weight & Body	log_biometrics	"My weight is 185 lbs today."
Sleep & Mood	log_sleep, log_mood	"I slept 7 hours and feel like an 8/10."
Fasting Status	get_fasting_status	"Am I still in my fasting window?"
Weight History	get_biometrics_history	"Show me my weight trend for the last 30 days."
Custom Metrics	log_custom_metric	"My blood pressure was 120/80 today."

📋 Goals, Habits & Reports

Set targets and get consolidated performance reviews.

• Habit Tracking (sparky_manage_habits): "Did I take my vitamins today?"
• Goal Management (sparky_manage_goals): "Set a new weight goal of 175 lbs by July."
• Weekly Reports (sparky_get_report): "Give me a weekly performance summary."
• Profile Settings (sparky_manage_profile): "Change my energy unit to kJ."

---

🕵️ AI Personalization (The "Health Detective")

Because the AI has access to all these tools, it can do things a standard app cannot:

• Correlation Detection: "I noticed your sleep quality is 20% better on days you finish your last meal before 7 PM."
• Smart Planning: "Based on your current weight trend and yesterday's activity, I recommend increasing your protein by 20g today."
• Inventory Logic: "You've logged Greek Yogurt 5 times this week. Should I add it to your high-protein shopping list?"

---

🔐 Security & Privacy

1. User Isolation (RLS): Normal MCP tools are restricted by PostgreSQL Row Level Security, scoped to the user authenticated by the API key. The AI can only see data belonging to that user.
2. Admin-Only Dev Tools: A small set of optional developer/debugging tools is off by default. They require an admin API key, plus either the Admin > System Settings toggle or the DEV_TOOLS_ENABLED=true environment variable, which forces them on regardless of the stored setting. These tools intentionally run with elevated database access (the owner pool, bypassing Row Level Security), so leave them disabled unless you are actively debugging.
3. Read-only API keys: Choose Access: Read-only when you generate a key for a client that should only read your data. Such a key only gets the tools that read, and tools that both read and write (such as sparky_manage_food) refuse their write actions. Outside MCP it can only make read requests. Keys created before this option existed keep full access.
4. Local First: If you run SparkyFitness locally, your data never leaves your infrastructure until you send it to your chosen AI provider (e.g., Anthropic or OpenAI).

🚀 Getting Started

The MCP server is served in-process by the main SparkyFitness server at POST /mcp. There is no separate MCP service to run.

1. Generate an API Key

Go to Settings → Developer & Integrations → API Key Management in the web UI and generate a key. Pick Read-only under Access if the assistant should only read your data. You'll pass this as a Bearer Token in the Authorization header.

2. Find Your MCP Endpoint

• Production: https://<your-host>/mcp (the production nginx config proxies /mcp to the server).
• Local dev: http://localhost:8080/mcp — the frontend Vite dev proxy forwards /mcp to the server. Hitting the server port directly at http://localhost:3010/mcp also works.

3. Configure Your Client

HTTP / remote-capable clients (Cursor and other clients that support streamable HTTP) point directly at /mcp with an Authorization: Bearer <API_KEY> header:

{
  "mcpServers": {
    "sparky-fitness": {
      "url": "https://<your-host>/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

stdio-only clients (such as the classic Claude Desktop config) can't talk HTTP directly. Use the off-the-shelf mcp-remote bridge. The key goes in an env block, and the header uses the no-space Authorization:${AUTH_HEADER} form — mcp-remote's documented workaround for clients that mangle spaces in header arguments (e.g. Claude Desktop on Windows, Cursor):

{
  "mcpServers": {
    "sparky-fitness": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<your-host>/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer <API_KEY>" }
    }
  }
}

Note: for a local-dev server over plain HTTP, add --allow-http to the args and use http://localhost:8080/mcp (or http://localhost:3010/mcp to hit the server directly) — mcp-remote refuses non-HTTPS URLs otherwise.

Open WebUI client (e.g. for locally hosted Ollama, Llama.cpp, etc.)

1. In Open WebUI, click your name in the bottom left and open the Admin Panel → Settings.
2. Scroll down to the Tools section and select Integrations.
3. Add a new connection:
   • Type: MCP Streamable HTTP (click 'OpenAPI' to change the option)
   • URL: The MCP url from above
   • Auth: Bearer
   • API Key: The API key from above
4. Save the options and refresh the web page. You can enable it on new chats through the Integration option.