MCP Beeminder Server

This project implements a Model Context Protocol (MCP) server for interacting with the Beeminder API.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardises how applications provide context to Large Language Models (LLMs). It acts like a "USB-C port for AI applications" - providing a standardised way to connect AI models to different data sources and tools.

MCP follows a client-server architecture where: - MCP Hosts: Programs like Claude Desktop or IDEs that want to access data through MCP - MCP Clients: Protocol clients that maintain 1:1 connections with servers - MCP Servers: Lightweight programs that expose specific capabilities through the standardised protocol - Local Data Sources: Your computer's files, databases, and services that MCP servers can securely access - Remote Services: External systems available over the internet that MCP servers can connect to

What is Beeminder?

Beeminder is a tool for overcoming akrasia (acting against your better judgment) by combining: - Quantified self-tracking - Visual feedback via a "Bright Red Line" (BRL) showing your commitment path - Financial stakes that increase with each failure - Flexible commitment with a 7-day "akrasia horizon"

This server implementation provides MCP-compatible access to Beeminder's API, allowing AI assistants to help users manage their Beeminder goals, datapoints, and other related functionality.

Features

The server provides access to core Beeminder functionality including: - Goal management (create, read, update, delete) - Datapoint management (create, read, delete) - User information retrieval - Support for all Beeminder goal types: - Do More ("hustler") - Odometer ("biker") - Weight Loss ("fatloser") - Gain Weight ("gainer") - Inbox Fewer ("inboxer") - Do Less ("drinker")

Running locally with the Claude Desktop app

Prerequisites

You'll need your Beeminder API key and username to run the server. To get your API key:

1. Log into Beeminder
2. Go to https://www.beeminder.com/api/v1/auth_token.json

You'll also need uv installed. See the uv docs for installation instructions. You can use something else but you'll need to change the command in the claude_desktop_config.json file.

Manual Installation

1. Clone this repository.
2. Add the following to your claude_desktop_config.json file:
3. On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
4. On Windows: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "beeminder": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/repo/mcp-beeminder",
      "run",
      "mcp-beeminder"
    ],
    "env": {
        "BEEMINDER_API_KEY": "YOUR_BEEMINDER_API_KEY,
        "BEEMINDER_USERNAME": "YOUR_BEEMINDER_USERNAME"
    }
  }
}

1. Install and open the Claude desktop app.
2. Try asking Claude to do a read/write operation of some sort to confirm the setup (e.g. list your Beeminder goals). If there are issues, use the Debugging tools provided in the MCP documentation here.

Acknowledgements

Thanks to @ianm199 for his beeminder-client package, on which this project is based.

And obviously thanks to the Beeminder team for building such a great product!