# Baremetrics MCP Server

An MCP (Model Context Protocol) server for the Baremetrics Metrics API. This server provides tools to query SaaS metrics like MRR, ARR, churn, and more.

## Installation

```bash
npm install
npm run build
```

## Configuration

Set your Baremetrics API key as an environment variable:

```bash
export BAREMETRICS_API_KEY=your_api_key_here
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "baremetrics": {
      "command": "node",
      "args": ["/path/to/baremetrics-mcp/dist/index.js"],
      "env": {
        "BAREMETRICS_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Available Tools

### `list_available_metrics`
Lists all available metrics that can be queried from Baremetrics.

### `show_summary`
Get daily summaries with all key metrics for a date range.

**Parameters:**
- `start_date` (required): Start date in YYYY-MM-DD format
- `end_date` (required): End date in YYYY-MM-DD format

### `show_metric`
Get detailed data for a specific metric over a date range.

**Parameters:**
- `metric` (required): The metric name (see available metrics below)
- `start_date` (required): Start date in YYYY-MM-DD format
- `end_date` (required): End date in YYYY-MM-DD format
- `compare_to` (optional): Number of days ago to compare to (default: 30)

### `show_metric_customers`
Get the customers that make up a specific metric (e.g., who upgraded, churned).

**Parameters:**
- `metric` (required): The metric name
- `start_date` (required): Start date in YYYY-MM-DD format
- `end_date` (required): End date in YYYY-MM-DD format

### `show_metric_plans`
Get a breakdown of a metric by plan across a date range.

**Parameters:**
- `metric` (required): The metric name
- `start_date` (required): Start date in YYYY-MM-DD format
- `end_date` (required): End date in YYYY-MM-DD format

### `show_cohorts`
Get cohort retention data with user and revenue tracking over time.

## Available Metrics

- `active_customers` - Currently active customers
- `active_subscriptions` - Currently active subscriptions
- `active_trials` - Currently active trials
- `arpu` - Average Revenue Per User
- `arr` - Annual Recurring Revenue
- `cancellations` - Subscription cancellations
- `churned_customers` - Customers who churned
- `converted_trials` - Trials that converted to paid
- `coupons` - Coupon usage
- `downgrades` - Subscription downgrades
- `failed_charges` - Failed payment charges
- `fees` - Processing fees
- `ltv` - Lifetime Value
- `mrr` - Monthly Recurring Revenue
- `mrr_growth_rate` - MRR growth rate
- `net_revenue` - Net revenue
- `net_revenue_churn` - Net revenue churn
- `new_customers` - New customers acquired
- `new_subscriptions` - New subscriptions
- `new_trials` - New trial signups
- `other_revenue` - Other revenue sources
- `plan_quantities` - Plan quantity changes
- `quick_ratio` - Quick ratio (growth efficiency)
- `reactivations` - Reactivated subscriptions
- `refunds` - Refunds issued
- `revenue_churn` - Revenue churn rate
- `trial_conversion` - Trial conversion rate
- `upgrades` - Subscription upgrades
- `user_churn` - User churn rate

## Example Usage

Once configured, you can ask Claude things like:

- "Show me my MRR for the last 30 days"
- "What's my churn rate between January and March?"
- "Which customers upgraded last month?"
- "Break down my ARR by plan"
- "Show me cohort retention data"

## License

MIT