# FitNotes MCP Server

An MCP server for analyzing your FitNotes ([Android](https://play.google.com/store/apps/details?id=com.github.jamesgay.fitnotes&hl=en_IN) & [iOS](https://apps.apple.com/us/app/fitnotes-workout-tracker/id1059245195)) workout data. Connect with an LLM to get context-aware insights, uncover training patterns, track progress, and receive personalized recommendations based on your own fitness history.

## Data

There are multiple ways to export your FitNotes data, such as exporting to CSV or using the "Android DB" option. Based on my experience, the "Android DB" export is better because it provides your workout data as a standard SQLite database with a decent schema out of the box. This makes it easy to explore and analyze and therefore the MCP server is designed to work directly with this database export.

## Quick Start

### 1. Setup Environment

```bash
# Navigate to the project directory
cd /path/to/fitnotes_mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -e .
```

### 2. Add Your FitNotes Data

Export your FitNotes data (Android DB export) and place the `.fitnotes` file in the project directory. The server will use the `FITNOTES_DB_PATH` environment variable to locate your database file.

### 3. Configure Claude Desktop

You can use any LLM that supports MCP. We'll use  Claude Desktop. Add the following to Claude desktop config.

[Check this](https://claudelog.com/configuration/#mcp-configuration) to know the location for the OS you are using.


```json
{
  "mcpServers": {
    "fitnotes-server": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["/path/to/mcp_fitnotes/run_server.py"],
      "cwd": "/path/to/mcp_fitnotes",
      "env": {
        "PYTHONPATH": "/path/to/mcp_fitnotes/src",
        "FITNOTES_DB_PATH": "/path/to/your/fitnotes.fitnotes"
      }
    }
  }
}
```

**Important**: Replace `/path/to/your/venv/bin/python` with your actual virtual environment Python path, `/path/to/mcp_fitnotes/` with your actual project directory, and `/path/to/your/fitnotes.fitnotes` with the actual path to your FitNotes database file.

### 4. Start Chatting!

Open Claude Desktop and start asking about your workouts:
- "How's my bench press progressing?"
- "What muscle groups am I neglecting?"
- "Show me my workout summary for the last month"
- "Find my personal records"

## Available MCP Tools

### Core Analysis Tools

1. **`get_database_schema`** - View complete database structure
2. **`get_database_metadata`** - Get workout statistics and overview  
3. **`execute_select_query`** - Run custom SELECT queries safely
4. **`get_sample_data`** - Explore table contents
5. **`get_workout_summary`** - Recent workout analysis with muscle group breakdown
6. **`analyze_exercise_progress`** - Detailed progress tracking for specific exercises
7. **`get_muscle_group_analysis`** - Training frequency and volume by muscle group

As you can see, the LLM does have a tool to execute queries but all database access is strictly read-only, with robust query validation to allow only safe SELECT statements. SQL injection protection is there and resource limits are enforced via query timeouts and result size caps.


### Example Conversations

**"How am I doing with my workouts lately?"**
 Uses `get_workout_summary` to show recent activity, PRs, and muscle group balance

**"Analyze my squat progress"**  
Uses `analyze_exercise_progress` to show weight progression, volume trends, and recent PRs

**"What exercises did I do yesterday?"**
Uses `execute_select_query` with a custom date filter

**"Am I training my back enough?"**
Uses `get_muscle_group_analysis` to compare back training with other muscle groups

**"What exercises do I have available?"**
Uses `execute_select_query` to get a list of all exercises from the database

**"Show me all my bicep exercises"**
Uses `execute_select_query` with custom filtering to find exercises by muscle group

## Example Analysis

Here's a real example of the kind of analysis you can get: 

> Show my chest training progress of the last 3 months. Also give me insights and improvement areas.

![Analysis Example 1](.readme_images/analysis-1.png)

![Analysis Example 2](.readme_images/analysis-2.png)

![Analysis Example 3](.readme_images/analysis-3.png)

![Analysis Example 4](.readme_images/analysis-4.png)

![Analysis Example 5](.readme_images/analysis-5.png) 


## Troubleshooting

**Server won't start?** Check that `FITNOTES_DB_PATH` environment variable points to your `.fitnotes` file and virtual environment is activated.

**Database file not found?** Verify the `FITNOTES_DB_PATH` variable points to the correct `.fitnotes` file path.

**Claude can't connect?** Verify MCP configuration paths in `claude_desktop_config.json` and restart Claude Desktop.