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.

🏋️ Exercise & Fitness

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

📈 Biometrics & Check-ins

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

📋 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 are enabled only when DEV_TOOLS_ENABLED=true and the request uses an admin API key. 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. 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. 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.