# revenuecat-charts-mcp

An MCP server that gives AI agents native access to [RevenueCat's Charts API](https://www.revenuecat.com/docs/api-v2). Ask your agent about MRR, churn, trials, revenue, and 17 more subscription metrics — in natural language.

Built by [Rev](https://rev.joeyco.dev), an AI agent applying to be RevenueCat's first Agentic AI Developer & Growth Advocate.

## Why

Agents are building and monetizing apps. But subscription analytics tools were designed for humans staring at dashboards.

This MCP server closes that gap. Install it, give your agent a RevenueCat API key, and it can check MRR trends, monitor churn, analyze trial conversions, and compare revenue by country — all through natural language.

## Quick Start

### Claude Code

```bash
claude mcp add revenuecat-charts-mcp -- node /path/to/revenuecat-charts-mcp/build/index.js
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "revenuecat-charts": {
      "command": "node",
      "args": ["/path/to/revenuecat-charts-mcp/build/index.js"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "revenuecat-charts": {
      "command": "node",
      "args": ["/path/to/revenuecat-charts-mcp/build/index.js"]
    }
  }
}
```

### From Source

```bash
git clone https://github.com/joeyaflores/revenuecat-charts-mcp.git
cd revenuecat-charts-mcp
npm install
npm run build
```

## Tools

### `rc_list_metrics`

List all 21 available chart metrics with descriptions.

```
"What subscription metrics can I query?"
"Show me the revenue-related metrics"
```

**Parameters:**
- `category` (optional): Filter by `revenue`, `actives`, `trials`, `conversion`, or `cohorts`. Default: `all`

### `rc_get_overview`

Get a real-time snapshot of key subscription health metrics. No date range needed.

```
"What's my current MRR?"
"Give me a subscription health check"
```

**Parameters:**
- `api_key` (required): RevenueCat secret API key (`sk_...`)
- `project_id` (optional): RevenueCat project ID. Auto-detected if omitted.

**Returns:** Active trials, active subscriptions, MRR, revenue, new customers, active users, and transaction count.

### `rc_get_chart`

Query any metric as a time series with flexible date ranges and resolution.

```
"Show me MRR for the last 12 months"
"What's my churn rate week over week this quarter?"
"Break down revenue by country for 2025"
```

**Parameters:**
- `api_key` (required): RevenueCat secret API key (`sk_...`)
- `metric` (required): One of 21 metric names (use `rc_list_metrics` to see all)
- `start_date` (required): Start date (`YYYY-MM-DD`)
- `end_date` (required): End date (`YYYY-MM-DD`)
- `resolution` (optional): `day`, `week`, or `month`. Default: `month`
- `segment` (optional): Segment by dimension (e.g., `country`)
- `project_id` (optional): RevenueCat project ID. Auto-detected if omitted.

**Returns:** Formatted markdown table with dates, all measures, and summary statistics.

## Available Metrics

| Category | Metrics |
|----------|---------|
| **Revenue** | `mrr`, `mrr_movement`, `arr`, `revenue`, `ltv_per_customer`, `ltv_per_paying_customer` |
| **Subscriptions** | `actives`, `actives_movement`, `actives_new`, `churn`, `refund_rate`, `subscription_status` |
| **Trials** | `trials`, `trials_movement`, `trials_new` |
| **Conversion** | `conversion_to_paying`, `customers_new`, `customers_active`, `trial_conversion_rate` |
| **Cohorts** | `subscription_retention`, `cohort_explorer` |

## Example Output

**Overview:**
```
# Subscription Overview

- **Active Trials**: 58  _(In total)_
- **Active Subscriptions**: 2,517  _(In total)_
- **MRR**: $4,534  _(Monthly Recurring Revenue)_
- **Revenue**: $4,747  _(Last 28 days)_
- **New Customers**: 1,623  _(Last 28 days)_
- **Active Users**: 14,062  _(Last 28 days)_
```

**Churn (monthly):**
```
| Date | Actives (#) | Churned Actives (#) | Churn Rate (%) |
| --- | --- | --- | --- |
| 2025-10-01 | 2,492 | 267 | 10.71% |
| 2025-11-01 | 2,403 | 165 | 6.87% |
| 2025-12-01 | 2,470 | 165 | 6.68% |
| 2026-01-01 | 2,471 | 188 | 7.61% |
| 2026-02-01 | 2,535 | 169 | 6.67% |
```

## Requirements

- Node.js 18+
- RevenueCat secret API key with Charts metrics permission

## License

MIT