Baremetrics MCP Server

An MCP (Model Context Protocol) server that provides read-only access to Baremetrics SaaS analytics. Query your MRR, ARR, churn, LTV, customers, subscriptions, and more directly from Claude.

Features

• 17 read-only tools covering metrics, customers, subscriptions, plans, charges, and events
• All key SaaS metrics — MRR, ARR, ARPU, LTV, churn, trial conversions, and more
• Cohort analysis for retention tracking
• Customer search and detailed event history
• Dual transport — works via stdio (Claude Code) or HTTP (any MCP client)
• Safe by design — every tool is annotated readOnlyHint: true, no write operations

Tools

Tool	Description
get_account	Get account info
list_sources	List connected data sources
get_metrics_summary	Summary of all metrics for a date range
get_metric	Time series for a single metric (MRR, ARR, churn, etc.)
get_metric_customers	Customers contributing to a metric
get_metric_plans	Plan-level breakout for a metric
get_cohorts	Cohort retention analysis
list_customers	List/search customers
get_customer	Get a single customer's details
list_customer_events	Events for a customer
list_subscriptions	List subscriptions
get_subscription	Get subscription details
list_plans	List all plans
get_plan	Get plan details
list_charges	List charges with filtering
get_charge	Get charge details
list_events	List events

All tools are read-only and annotated with readOnlyHint: true.

Setup

Prerequisites

• Node.js 18+
• A Baremetrics API key (get one here)

Install & Build

npm install
npm run build

Run with Claude Code (stdio)

claude mcp add baremetrics -- node /path/to/bm-mcp/build/index.js --stdio

Or add to your Claude Code settings with the API key:

{
  "mcpServers": {
    "baremetrics": {
      "command": "node",
      "args": ["/path/to/bm-mcp/build/index.js", "--stdio"],
      "env": {
        "BAREMETRICS_API_KEY": "your-api-key"
      }
    }
  }
}

Run with Cursor

1. Open Cursor Settings (Ctrl+Shift+J or Cmd+, on Mac)
2. Go to MCP in the sidebar
3. Click Add new MCP server and enter:

{
  "mcpServers": {
    "baremetrics": {
      "command": "node",
      "args": ["/path/to/baremetrics-mcp-server/build/index.js", "--stdio"],
      "env": {
        "BAREMETRICS_API_KEY": "your-api-key"
      }
    }
  }
}

4. Restart Cursor — the Baremetrics tools will appear in the MCP panel.

Run as Streamable HTTP Server

BAREMETRICS_API_KEY=your-key node build/index.js

The server listens on port 3000 by default. Set MCP_PORT to change it.

Environment Variables

Variable	Required	Description
BAREMETRICS_API_KEY	Yes	Your Baremetrics API key
MCP_PORT	No	HTTP server port (default: 3000)

Usage Examples

1. Get a summary of your key metrics

User prompt: "Show me a summary of my SaaS metrics for the last 30 days."

Expected tool calls:

1. get_metrics_summary with start_date: "2026-02-09", end_date: "2026-03-11"

Expected output:

MRR: $45,200.00
ARR: $542,400.00
Active Customers: 312
ARPU: $144.87
LTV: $2,840.00
User Churn: 3.20%
Revenue Churn: 2.80%
New Customers: 18
Upgrades: 7
Downgrades: 3

2. Analyze churn over time

User prompt: "What has my revenue churn looked like month-over-month this year?"

Expected tool calls:

1. get_metric with metric: "revenue_churn", start_date: "2026-01-01", end_date: "2026-03-11"

Expected output:

Revenue Churn (basis points, 500 = 5.00%):

2026-01-01: 320 (3.20%)
2026-02-01: 280 (2.80%)
2026-03-01: 310 (3.10%)

Each data point includes the date and churn value. If compare_to is provided, a previous object shows the prior period value and percent change.

3. Look up a specific customer

User prompt: "Find the customer with email [email protected] and show me their subscription history."

Expected tool calls:

1. list_sources — retrieves available source IDs
2. list_customers with source_id: "src_abc123", search: "[email protected]"
3. get_customer with source_id: "src_abc123", customer_oid: "cus_xyz789"
4. list_customer_events with source_id: "src_abc123", customer_oid: "cus_xyz789"

Expected output:

Customer: Alice Johnson ([email protected])
Current MRR: $99.00
LTV: $1,188.00
Status: Active

Events:
- 2025-06-15: new_customer — Subscribed to Pro Monthly ($99.00/mo)
- 2025-09-01: upgrade — Pro Monthly → Business Monthly ($199.00/mo)
- 2026-01-10: downgrade — Business Monthly → Pro Monthly ($99.00/mo)

4. Compare plans by MRR contribution

User prompt: "Break down my MRR by plan."

Expected tool calls:

1. get_metric_plans with metric: "mrr", start_date: "2026-03-01", end_date: "2026-03-11"

Expected output:

MRR by Plan (2026-03-11):

Pro Monthly:      $22,770.00  (230 subscriptions)
Business Monthly: $15,920.00  (80 subscriptions)
Enterprise Annual: $5,410.00  (12 subscriptions)
Starter Monthly:  $1,100.00   (55 subscriptions)

Each entry shows the plan name, billing interval, and its contribution to the selected metric.

Troubleshooting

Issue	Cause	Solution
"Unauthorized: Invalid or missing Baremetrics API key"	API key is missing, expired, or incorrect	Verify your key at Baremetrics API settings and update your BAREMETRICS_API_KEY environment variable
"Rate limited" error	Exceeded 3,600 requests/hour	Wait a few minutes and retry. Avoid requesting very wide date ranges repeatedly
"Request timed out after 30 seconds"	Date range too wide or API slow	Use a narrower date range (under 12 months for cohorts, under 6 months for metric summaries)
Tool requires source_id but none provided	Most tools need a source ID from your Baremetrics account	Call list_sources first to get your source IDs, then pass one to the tool
Empty results	No data in the requested date range or source	Verify the date range contains data in your Baremetrics dashboard. Check that you're using the correct source_id

Privacy Policy

This MCP server acts as a pass-through to the Baremetrics API. It does not store, log, or transmit your data to any third party beyond Baremetrics itself.

• Data collected: None. All requests are forwarded directly to the Baremetrics API using your API key.
• Data storage: No data is persisted by this server. All responses are returned directly to the MCP client.
• Third-party sharing: None. Data flows only between the MCP client and Baremetrics.
• Data retention: None. This server is stateless.
• Contact: For questions about Baremetrics data handling, see Baremetrics Privacy Policy.

Support

For issues with this MCP server, please open an issue on the GitHub repository.

For questions about your Baremetrics data or API, contact Baremetrics Support.

License

MIT