# Metabolic Estimator MCP

> The Metabolic Energy Estimator MCP Server handles deterministic calorie and energy math for fitness agents. It calculates Basal Metabolic Rate (BMR) and Total Daily Energy Expenditure (TDEE) using the Mifflin-St Jeor equation, finds exact calories burned from specific activities via a local catalog of 80+ exercises, and projects precise timelines for reaching weight goals based on defined deficits.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** metabolic-calculation, fitness-tracking, tdee, weight-loss, health-data, activity-tracking

## Description

The `calculate_tdee` tool determines your Total Daily Energy Expenditure (TDEE) and Basal Metabolic Rate (BMR). You input your current weight, height, age, and activity level; it runs those numbers through the established Mifflin-St Jeor equation to give you precise calorie targets. This isn't guesswork—it's deterministic math. The BMR tells you what calories you burn just keeping your organs running; TDEE accounts for everything else you do throughout a day. When your agent needs to know your baseline energy requirements, it calls this tool. You never send sensitive health data anywhere outside the local process.

The server also provides four key tools that handle every metabolic calculation, so you don't have to trust any random LLM guess. First, if you need background activity data, the `search_activity_catalog` tool pulls from a local database of physical activities. It gives you the official Metabolic Equivalent of Task (MET) value for anything listed in its 80-plus exercise catalog. These MET values are critical because they are the industry standard for measuring energy output.

Once you've got that MET value, the `estimate_calories_burned` tool calculates exactly how many calories you burned during a specific workout. You just feed it an activity ID (which comes from the catalog search), your current weight, and the duration of time you worked out. The result is a precise calorie count for that session. It’s not rounded; it's calculated based on established metabolic science.

For planning, the `calculate_weight_loss_projection` tool figures out exactly how long it will take to hit your weight goal. You give it two simple numbers: your target weight and the daily calorie deficit you plan to maintain. The tool runs the math and tells you, in days or weeks, precisely when you’ll reach that number. This function handles the full timeline projection, making sure you know what's coming up.

Your AI client doesn't guess at energy expenditure; it runs verified calculations every time. It calculates your baseline needs using age, weight, height, and activity level via `calculate_tdee`. You can find specific MET values for any listed exercise by calling `search_activity_catalog`. Then, you plug those metrics into the system to get an exact calorie burn rate using `estimate_calories_burned`, factoring in your body weight and workout length. Finally, if you're mapping out a plan, the server computes the total time—in days or weeks—required to hit a target weight by maintaining a specified daily deficit amount through `calculate_weight_loss_projection`. You just plug in the variables and get the definite answer.

## Tools

### calculate_tdee
Uses weight, height, age, and activity level to calculate your Total Daily Energy Expenditure (TDEE) and Basal Metabolic Rate (BMR).

### estimate_calories_burned
Calculates precise calories burned using an activity ID, your current weight, and workout duration.

### search_activity_catalog
Searches a local database for physical activities and returns their official Metabolic Equivalent of Task (MET) values.

### calculate_weight_loss_projection
Takes a target weight and daily deficit amount to project the exact number of days and weeks needed for loss.

## Prompt Examples

**Prompt:** 
```
I weigh 80kg and ran moderately for 45 minutes. How many calories did I burn?
```

**Response:** 
```
Using the search_activity_catalog and estimate_calories_burned tools: The activity 'run_moderate' has a MET of 9.8. You burned approximately 588 calories.
```

**Prompt:** 
```
I am a 30-year-old male, 180cm, 85kg, with a sedentary lifestyle. What is my TDEE?
```

**Response:** 
```
Using the calculate_tdee tool: Your BMR is 1830 kcal/day and your Total Daily Energy Expenditure (TDEE) is roughly 2196 kcal/day.
```

**Prompt:** 
```
I weigh 90kg and want to reach 80kg with a 500 calorie daily deficit. How long will it take?
```

**Response:** 
```
Using the calculate_weight_loss_projection tool: To lose 10kg, you need to burn 77,000 calories. At a 500/day deficit, it will take exactly 154 days (22 weeks).
```

## Capabilities

### Calculate Baseline Energy Needs
The tool calculates your Total Daily Energy Expenditure (TDEE) and Basal Metabolic Rate (BMR) using standard formulas based on age, weight, height, and activity level.

### Identify Activity MET Values
The server searches a local catalog to find the specific Metabolic Equivalent of Task (MET) value for any listed physical activity.

### Determine Burn Calories
It calculates the exact number of calories burned by running a specific activity, given your weight and how long you worked out.

### Project Weight Loss Timeline
The server computes the total days or weeks required to hit a target weight based on maintaining a specified daily calorie deficit.

## Use Cases

### Setting up a new user's baseline plan
A developer needs an agent to welcome a new client. The agent first calls `calculate_tdee` using the client's age, height, and weight. This establishes the Total Daily Energy Expenditure (TDEE) before any activity logging happens, setting realistic expectations from day one.

### Logging a specific workout session
A user finishes an hour of moderate running. The agent first calls `search_activity_catalog` to get the Activity ID for 'run_moderate'. Then, it passes that ID, along with the user's weight and 60 minutes, into `estimate_calories_burned` to return a precise calorie count.

### Creating a long-term goal roadmap
A client wants to lose 15kg. The agent calculates the total required deficit (77,000 calories) and then uses `calculate_weight_loss_projection` with an expected daily deficit of 600 calories to output a clear timeline: exactly 22 weeks.

### Comparing activity intensity
The agent needs to compare cycling versus swimming. It calls `search_activity_catalog` for both activities, pulling the MET values. This allows it to explain why one activity burns more calories per minute than another, using deterministic data.

## Benefits

- Eliminates guesswork. Instead of relying on vague LLM estimates for calories burned, use `estimate_calories_burned` with a specific activity ID to get mathematically exact results based on weight and time.
- Establishes accurate baselines instantly. The `calculate_tdee` tool uses the Mifflin-St Jeor equation to give you your real Basal Metabolic Rate (BMR) and Total Daily Energy Expenditure (TDEE), without sending any sensitive metrics over the wire.
- Provides clear goal paths. Use `calculate_weight_loss_projection` to tell users exactly how many days or weeks they need to maintain a specific caloric deficit to reach their target weight.
- Uses deterministic data. The `search_activity_catalog` function provides reliable MET values for over 80 activities, ensuring your calculations are based on an authoritative source, not general knowledge.
- Builds trust with numbers. By providing measurable metrics (like TDEE and BMR), your agent moves from giving advice to delivering verifiable data points.

## How It Works

The bottom line is: it replaces vague estimations with deterministic calculations using established scientific formulas and local data lookups.

1. First, your AI client calls `calculate_tdee` with your age, height, weight, and activity level. This establishes your baseline energy requirement.
2. Next, you use `search_activity_catalog` to find the correct Activity ID for your exercise (e.g., 'run_moderate'). Then, call `estimate_calories_burned` using that ID, along with your weight and time.
3. Finally, if you set a goal, calling `calculate_weight_loss_projection` takes the target weight and deficit amount to output a precise timeline.

## Frequently Asked Questions

**How does calculate_weight_loss_projection handle the 7700 calories per kg rule?**
It uses the standard scientific metric of 1kg of body fat equaling approximately 7,700 calories. You just need to provide your target weight and the daily deficit amount.

**Do I need search_activity_catalog before running estimate_calories_burned?**
Yes. `estimate_calories_burned` requires an `activityId`. You must run `search_activity_catalog` first to get the specific ID for the activity you want to track.

**Is the TDEE calculation safe?**
Yes. The server runs the Mifflin-St Jeor equation locally, meaning your health metrics never leave your environment or go up to a cloud service.

**Can I use estimate_calories_burned for weightlifting?**
Yes, as long as 'weightlifting' is in the catalog. You must first run `search_activity_catalog` to verify its activity ID and MET value for accurate results.

**Does running `calculate_tdee` send my health data to a cloud server?**
No, the calculation runs locally on the Vurb engine. Your Basal Metabolic Rate and Total Daily Energy Expenditure never leave your private environment.

**What error handling should I expect when using `calculate_weight_loss_projection`?**
If inputs are invalid (like negative weight or deficit), the tool returns a structured error object. Always validate that all provided metrics are positive numbers.

**Are there rate limits for calling `estimate_calories_burned`? **
Vinkius manages underlying API throughput, but we recommend implementing exponential backoff logic in your agent client. Check the service dashboard for specific usage caps.

**How does `search_activity_catalog` determine which activities are available?**
It queries a deterministic, local index of over 80 physical activities. This means you get immediate access to verified MET values without needing external API calls or network lookup delays.

**How does it calculate the calories burned?**
The estimate_calories_burned tool uses the standard metabolic formula: Calories = MET * weight(kg) * time(hours). It pulls the exact MET value from its internal activity catalog.

**What formula is used for Basal Metabolic Rate (BMR)?**
The calculate_tdee tool uses the Mifflin-St Jeor equation, which is currently considered the most accurate standard for predicting resting metabolic rate.

**How does it project weight loss?**
The calculate_weight_loss_projection tool uses the biological constant that 1kg of body fat equals approximately 7700 calories. It divides the total required deficit by your daily deficit to predict the exact timeline.