# Beeminder MCP

> Beeminder connects your personal commitment goals to any AI agent. You track progress, log metrics, and monitor goal status without leaving your workspace. It turns tracking self-improvement into a natural conversation with your agent.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** goal-tracking, habit-formation, data-points, self-improvement, quantified-self, api-integration

## Description

Using this MCP, you embed goal accountability directly into your daily workflow. Instead of logging into a separate habit tracker or manually updating spreadsheets, your AI client handles it all through simple conversation. You can list and inspect every active commitment to see exactly what you've pledged to do. Need to update your progress? Your agent adds new data points or adjusts existing ones on the fly. It even checks real-time status colors and provides summaries so you know if you’re falling behind before it becomes a problem. This gives you an instant view of your 'Yellow Brick Road,' letting you manage commitments right from Vinkius, alongside thousands of other services.

## Tools

### add_datapoint
Adds a new, measurable data point to an active goal.

### delete_datapoint
Removes a datapoint from a goal's history when the original entry was wrong.

### get_goal_status
Checks the current progress status of a goal to see if it's on track or at risk.

### get_goal
Retrieves detailed information about a specific, named goal.

### get_user_info
Retrieves your basic Beeminder profile details.

### list_charges
Lists recent financial pledges and associated charges on the account.

### list_datapoints
Retrieves all historical data points logged for a specific goal.

### list_goals
Lists every active commitment and goal set up on the account.

### refresh_goal
Manually triggers an update for a goal to ensure the system has the latest data.

### update_datapoint
Changes the value of an existing datapoint instead of deleting and adding a new one.

## Prompt Examples

**Prompt:** 
```
List all my active Beeminder goals.
```

**Response:** 
```
I've retrieved your goals. You have 3 active goals: 'Gym' (slug: gym), 'Reading' (slug: books), and 'Coding' (slug: project-x). Would you like the status for any of these?
```

**Prompt:** 
```
Log 500 words to my 'Reading' goal.
```

**Response:** 
```
Done! I've added a datapoint of 500 to your 'Reading' goal (slug: books). Your road status is now green.
```

**Prompt:** 
```
Check status for goal 'gym'.
```

**Response:** 
```
The goal 'Gym' is currently yellow. You have 2 days until derailment. You need to add a datapoint soon to stay on the road!
```

## Capabilities

### Check all current goals
List and inspect every active goal you've set up.

### Log new metrics
Add fresh data points (like words written or gym minutes) to any specific goal.

### Manage existing data
Update or delete datapoints associated with a goal if the original log was incorrect.

### Get commitment status
Check the immediate, real-time road status color and summary for any goal.

### Audit pledges
List recent charges or financial pledges tied to your account history.

## Use Cases

### I need to check if I’m going to miss my quarterly goal.
My agent checks the current status using `get_goal_status`. It tells me that since I haven't logged data in two weeks, I'm yellow. Then, it lets me use `list_datapoints` to see exactly how far off track I am from my target.

### I finished a large chunk of work and need to log the progress.
I ask my agent to log 1200 words for my book goal. The agent uses `add_datapoint` and confirms my road status has improved, all in one conversational step.

### My team needs a report on who is actively logging goals.
I ask the agent to list all active goals using `list_goals`, giving me an immediate overview of everyone’s current commitments that need monitoring.

## Benefits

- Stop manual data entry. Instead of logging into a separate site to update your metrics, you just talk to your agent and use the `add_datapoint` tool.
- Know your risk instantly. You can check commitment status using `get_goal_status`, which tells you immediately if your goal is yellow or red.
- Keep records clean. If you enter a datapoint incorrectly, use `update_datapoint` to change the number instead of deleting and re-adding it.
- Get full visibility into commitments. Use `list_goals` to see every single thing you've pledged to do in one go.
- Review your finances easily. The `list_charges` tool gives you an immediate audit of all recent pledges associated with the account.

## How It Works

The bottom line is: you talk to your agent like talking to a dashboard, and it handles the complex data calls in the background.

1. First, subscribe to this MCP and enter your Beeminder Username and Auth Token.
2. Next, tell your AI agent the goal you want to check or update.
3. Finally, the agent executes the required action—like logging data points or checking status—and gives you a direct answer.

## Frequently Asked Questions

**How do I list all my active goals using list_goals?**
You simply ask your agent to run `list_goals`. It returns a clean roster of every commitment you have made, giving you an immediate inventory.

**What if I need to check the status for multiple goals? Is there a single tool?**
No single tool handles that. You'll need to ask your agent to run `get_goal_status` for each specific goal you want checked.

**Can I find out how much money I’ve pledged using list_charges?**
Yes, running `list_charges` provides a full rundown of your recent pledges and any associated financial obligations on the account.

**I want to see my goals' data over time. Which tool should I use?**
Use `list_datapoints`. This pulls all historical metrics for one specific goal, letting you graph your progress and spot trends in your commitment.

**Before I start tracking goals, how do I test my credentials using get_user_info?**
It retrieves your basic Beeminder profile details. This is the best way to confirm that your authentication token works correctly before you try modifying any goal data.

**If I logged a datapoint incorrectly, should I use update_datapoint or delete_datapoint?**
Use `update_datapoint` if the metric was recorded but the value is wrong. If the original entry was never meant to be there at all, then you'll want to call `delete_datapoint`.

**My goal status seems stale; how do I manually force a data refresh using refresh_goal?**
This tool immediately triggers a pull of the latest commitment numbers from Beeminder. It's crucial for ensuring your agent sees real-time updates and accurate progress metrics.

**I only want to see the raw, structured data points for one specific goal; how do I use list_datapoints?**
`list_datapoints` pulls a detailed log of every metric recorded against that single goal slug. This gives you granular access to historical data separate from just checking the overall status.

**Can I add a new datapoint to a goal from the agent?**
Yes! Use the `add_datapoint` action with the goal slug and the value. You can also add an optional comment. Your agent will log it to Beeminder instantly.

**How do I check if I'm in danger of derailing on a goal?**
Simply ask the agent to `get_goal_status` with the Goal Slug. It will return the road status color (e.g., green, yellow, orange, red) and a summary of how much time or value remains.

**Does the integration allow me to create new goals?**
Currently, the toolset focuses on managing existing goals (logging data, checking status). Creating new goals with complex 'Yellow Brick Road' configurations must be done on the Beeminder website.