MCP Beeminder Integration Service

This repository furnishes an implementation of a Model Context Protocol (MCP) endpoint designed for seamless interaction with the Beeminder service API.

Understanding MCP

The Model Context Protocol (MCP) establishes an open standard for furnishing context to Large Language Models (LLMs). Think of it as the universal adapter—the "USB-C port for AI systems"—providing a consistent mechanism to bridge AI models with diverse data repositories and functional utilities.

MCP operates on a distributed architecture: - MCP Consumers (Hosts): Applications like Claude Desktop or IDEs seeking data access via MCP. - Protocol Clients: Entities maintaining dedicated connections to servers. - MCP Providers (Servers): Minimalist software components exposing specific functionalities through the standardized protocol. - Local Context Stores: Internal assets such as local files, proprietary databases, and on-premise services accessible securely by MCP Providers. - External Systems: Remote web services that MCP Providers can interface with.

What is Beeminder?

Beeminder is a specialized platform designed to combat akrasia (the gap between intent and action) by unifying several mechanisms: - Empirical self-measurement and quantitative self-tracking. - Vivid visual representation of adherence via the "Bright Red Line" (BRL) charting the required commitment trajectory. - Introduction of financial penalties that escalate upon deviations from the plan. - Adjustable commitment structures incorporating a rolling seven-day "akrasia horizon."

This server component offers MCP-compliant access to Beeminder's interface, empowering intelligent agents to manage user goals, log datapoints, and utilize other associated features.

Core Capabilities

The service exposes interfaces for essential Beeminder operations, including: - Management of goals (instantiation, retrieval, modification, termination). - Management of individual datapoints (entry, fetching, removal). - Querying of user profile details. - Comprehensive support spanning all Beeminder objective archetypes: - Performance enhancement ("hustler" / Do More) - Cumulative tracking ("biker" / Odometer) - Body mass reduction ("fatloser" / Weight Loss) - Body mass gain ("gainer" / Gain Weight) - Volume reduction ("inboxer" / Inbox Fewer) - Performance restriction ("drinker" / Do Less)

Local Deployment utilizing the Claude Desktop Client

Requirements

Execution requires your personal Beeminder API secret and associated account name. Acquire your API credential via:

1. Logging into your Beeminder account.
2. Navigating to https://www.beeminder.com/api/v1/auth_token.json

You must also have the uv package manager installed. Refer to the uv documentation for setup guidance. Alternative package managers are viable, provided the command directive within claude_desktop_config.json is updated accordingly.

Setup Procedure (Manual)

1. Obtain a local copy of this repository via cloning.
2. Insert the configuration block below into your claude_desktop_config.json file, located at:
3. macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
4. 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. Launch and ensure the Claude desktop application is running.
2. Verify the integration by prompting Claude to execute a data retrieval or modification action concerning Beeminder (e.g., request a summary of active goals). Refer to the MCP debugging resources here if configuration errors arise.

Credits

Appreciation extends to @ianm199 for developing the beeminder-client library, which served as the foundation for this project.

And, naturally, gratitude to the entire Beeminder team for creating such an exceptional utility!