GrowthOS

Answer growth questions in plain English. No SQL required.

Project status

Experimental beta. Snapshot date: 2025-12-15. The strongest current evaluation path is weekly growth review, funnel diagnosis, and channel efficiency review. See STATUS.md and KNOWN_LIMITATIONS.md.

GrowthOS is an open-source MCP analytics server that connects your AI assistant (Claude, Cursor, or any MCP-compatible client) directly to your marketing and product data. Ask questions about funnels, retention, CAC, churn, anomalies, channel performance, forecasts, Shapley attribution, and narrative summaries — and get structured, benchmark-referenced answers in seconds.

Related MCP server: Marketing MCP Server

Screenshots

REST API (Swagger UI)

What GrowthOS Does

Claude / Cursor / any MCP client
             │
             ▼
┌──────────────────────────────┐
│        GrowthOS MCP Server   │                GrowthOS sits between your AI assistant and your data
│  49 tools · DuckDB · SQL     │                It exposes **49 MCP tools** that your AI can call to run real analysis — funnel breakdowns, CAC/LTV calculations, cohort retention matrices,
│  Semantic layer · Benchmarks │                anomaly detection, SQL queries, and more — then formats results with benchmark comparisons so you get context, 
└────────────┬─────────────────┘                not just numbers.
             │
   ┌──────────────────────┐
   │   Your data sources  │
   │  CSV · PostgreSQL    │
   │  Stripe · Meta Ads   │
   │  Google Ads · HubSpot│
   │  Mixpanel · Amplitude│
   └──────────────────────┘

5 Questions GrowthOS Answers Reliably

1. "Why did CAC increase last week and is it sustainable?" Channel-level CAC, LTV, and ROAS with automated invest/cut/watch classification.

2. "Where is our funnel breaking and what should we test first?" Step-by-step conversion rates with the biggest drop-off identified automatically.

3. "How bad is our retention and how does it compare to benchmarks?" Cohort retention matrix vs. B2B SaaS medians with Good / Average / Poor rating.

4. "Which users are at risk of churning and how do we bring them back?" Active / At-Risk / Churned segmentation using configurable inactivity thresholds.

5. "What will our spend and signups look like in the next 30 days?" Linear regression and exponential smoothing forecasts with confidence bands.

Who It's For

• Growth teams who want fast, repeatable answers without waiting for a data analyst

• Founders and PMs reviewing weekly metrics in Claude, Cursor, or any AI

• Marketing ops managing multi-channel attribution across Google, Meta, Stripe, HubSpot, Mixpanel, Amplitude, and CSV exports

Who It's Not For

• Teams that need dashboards or BI charts (use Metabase, Looker, etc.)

• Real-time streaming data (GrowthOS reads CSV/DuckDB snapshots)

• Enterprise RBAC or multi-tenant data isolation

Quick Start

Install

pip install growth-os

Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "growth-os": {
      "command": "uvx",
      "args": ["growth-os"],
      "env": {
        "GROWTH_DATA_DIR": "/path/to/your/csv/folder"
      }
    }
  }
}

Cursor / Windsurf / any MCP client

{
  "mcpServers": {
    "growth-os": {
      "command": "uvx",
      "args": ["growth-os"],
      "env": {
        "GROWTH_DATA_DIR": "./data"
      }
    }
  }
}

From source

git clone https://github.com/Astoriel/GrowthOS.git
cd GrowthOS
pip install -e ".[dev]"
python -m growth_os.server

Demo Mode — No Data Required

Skip GROWTH_DATA_DIR entirely. GrowthOS auto-generates realistic sample marketing data on startup — useful for exploring all 49 tools before connecting real data. Every connector (HubSpot, Mixpanel, Amplitude, Stripe, Meta, Google Ads) also runs in demo mode with synthetic mock data when credentials are absent.

Try it immediately:

pip install growth-os
# In Claude: "Give me a weekly growth summary"
# GrowthOS responds with real analysis on auto-generated sample data

Data Sources and Connectors

CSV Mode

Point GROWTH_DATA_DIR at a folder containing CSV files. GrowthOS loads all CSVs as queryable DuckDB tables.

export GROWTH_DATA_DIR=/path/to/csv/folder

Recommended file names (auto-detected schema):

Column names are flexible — use suggest_attribution_mappings to auto-map aliases.

PostgreSQL Mode

export POSTGRES_URL=postgresql://user:pass@host:5432/dbname

GrowthOS attaches PostgreSQL as a read-only DuckDB extension. All queries are read-only; write/DDL operations are blocked at the AST level.

Stripe

export STRIPE_API_KEY=sk_live_...

Syncs invoices, subscriptions, charges, and events. Call sync_stripe_billing from your AI assistant.

Meta Ads

export META_ACCESS_TOKEN=...
export META_AD_ACCOUNT_ID=act_...
export META_API_VERSION=v21.0   # optional, default v21.0

Syncs campaigns and daily ad insights. Call sync_meta_ads.

Google Ads

export GOOGLE_ADS_DEVELOPER_TOKEN=...
export GOOGLE_ADS_CUSTOMER_ID=...
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=...   # manager account ID, if applicable
export GOOGLE_ADS_ACCESS_TOKEN=...
export GOOGLE_ADS_REFRESH_TOKEN=...
export GOOGLE_ADS_CLIENT_ID=...
export GOOGLE_ADS_CLIENT_SECRET=...
export GOOGLE_ADS_API_VERSION=v19         # optional, default v19

Syncs campaigns and click performance. Call sync_google_ads.

HubSpot

Uses a Private App access token (not an API key). Create a Private App in HubSpot Settings → Integrations → Private Apps, and grant these scopes:

• crm.objects.contacts.read

• crm.objects.deals.read

export HUBSPOT_ACCESS_TOKEN=pat-eu1-...   # Private App token
export HUBSPOT_BASE_URL=https://api.hubapi.com  # optional

Call sync_hubspot to pull contacts and deals. Falls back to demo mode (100–200 mock rows) when HUBSPOT_ACCESS_TOKEN is unset.

Mixpanel

Uses the API Secret from Project Settings (not the project token).

export MIXPANEL_API_SECRET=...          # Project API Secret
export MIXPANEL_PROJECT_ID=...          # Project numeric ID (optional)
export MIXPANEL_EU=true                 # true = EU data residency (default)

Call sync_mixpanel to pull event streams and funnel data. Funnel data falls back to mock if the account is on the free plan (HTTP 402). Falls back to demo mode (up to 500 mock events + 3 funnel templates) when MIXPANEL_API_SECRET is unset.

Amplitude

Requires both the API Key and Secret Key from the Amplitude project settings (under General → API Keys). Note: the JavaScript SDK snippet key is a different key and will not work here.

export AMPLITUDE_API_KEY=...            # From Project Settings → API Keys
export AMPLITUDE_SECRET_KEY=...         # Secret key (required alongside API key)
export AMPLITUDE_EU=true                # true = EU data residency (default)

Call sync_amplitude to pull events and user cohorts. Falls back to demo mode (500 mock events + 8 mock cohorts) when either key is missing.

REST API Server

Run GrowthOS as a standalone HTTP API alongside the MCP server:

pip install "growth-os[api]"
growth-os-api

The API server starts at http://localhost:8000. Swagger docs at http://localhost:8000/docs.

Sample Prompts

All prompts work in demo mode or with real data.

Weekly review:

"Give me a weekly growth summary comparing this week to last week."

Funnel diagnosis:

"Analyze the signup → activation → purchase funnel and tell me where we're losing users."

CAC/LTV:

"What's our CAC and LTV by channel? Which channels should we scale up?"

Retention check:

"How is our month-1 retention trending and how does it compare to SaaS benchmarks?"

Churn investigation:

"How many users churned last month and how many are at risk right now?"

Anomaly investigation:

"Something looks off in our spend last Tuesday. Detect any anomalies in marketing_spend."

Shapley attribution:

"Compute Shapley-value attribution across all channels for the last 90 days."

Forecasting:

"Forecast our daily signups for the next 30 days using linear trend and exponential smoothing."

Narrative review:

"Write a plain-English growth narrative with headline findings and a recommendation."

Data drift alert:

"Alert me via webhook if spend drifts more than 15% compared to last week."

HubSpot contacts:

"Sync our HubSpot contacts and show a breakdown by lifecycle stage."

Profile setup:

"Save my current setup as a profile called 'production' for next session."

Tool Reference

All 49 registered MCP tools:

Discovery

Analysis

Workflow Tools (Combined Multi-Step Analysis)

Forecasting

Reports

Data Quality

Attribution Mapping

Integrations

Workspace Profiles

Workspace Profiles and Custom Metrics

Save any combination of data directory, Postgres URL, and business mode as a named profile:

> "Save my current setup as a profile called 'production'."
> "Load the 'production' profile."

Profiles support custom metric definitions — define SQL-based KPIs with benchmark thresholds and units that GrowthOS evaluates alongside built-in metrics:

> "Add a custom metric: 'avg_order_value' = revenue / orders, benchmark 45, unit USD."

Architecture

src/growth_os/
├── app/
│   ├── server.py         # FastMCP server factory
│   ├── registry.py       # 49 MCP tool registrations
│   └── lifespan.py       # Startup sample data provisioning
├── api/
│   └── server.py         # FastAPI REST API (optional)
├── config/
│   ├── settings.py       # Pydantic-settings env config
│   └── profiles.py       # Workspace profiles + custom metrics
├── connectors/
│   ├── duckdb.py         # DuckDB engine + query cache
│   ├── csv.py            # CSV ingestion
│   ├── postgres.py       # PostgreSQL attach (read-only)
│   ├── stripe.py         # Stripe Billing API
│   ├── meta_ads.py       # Meta Marketing API
│   ├── google_ads.py     # Google Ads API
│   ├── hubspot.py        # HubSpot CRM v3 (contacts + deals)
│   ├── mixpanel.py       # Mixpanel Export + Funnels API
│   ├── amplitude.py      # Amplitude Export + Cohorts API
│   └── webhook.py        # Outbound webhook dispatcher
├── domain/
│   ├── models.py         # ToolEnvelope, shared models
│   ├── exceptions.py     # ConnectorError, QueryError
│   ├── enums.py          # FreshnessStatus, Severity, ChurnMode
│   └── contracts.py      # Schema contracts for validation
├── ingestion/
│   ├── catalog.py        # Table catalog
│   ├── freshness.py      # Freshness detection
│   ├── validators.py     # Data quality validators
│   ├── mapping.py        # Attribution mapping engine
│   └── loaders.py        # Data loading orchestration
├── observability/
│   ├── logging.py        # Structured JSON logging
│   ├── tracing.py        # @trace decorator
│   └── audit.py          # Append-only audit log
├── presentation/
│   └── markdown.py       # ToolEnvelope formatter + narrative builder
├── query/
│   ├── safety.py         # AST-based SQL validator (sqlglot)
│   └── builder.py        # Query builder
├── semantic/
│   ├── metrics.py        # CAC, LTV, churn (3 modes), ROAS
│   ├── benchmarks.py     # B2B SaaS benchmark data
│   ├── funnels.py        # Funnel step definitions
│   ├── retention.py      # Retention cohort logic
│   ├── attribution.py    # UTM attribution + Shapley values
│   └── forecasting.py    # Linear OLS + exponential smoothing
├── services/
│   ├── analysis_service.py
│   ├── catalog_service.py
│   ├── diagnostics_service.py
│   ├── reporting_service.py
│   ├── integration_service.py
│   ├── notification_service.py
│   └── forecasting_service.py
├── demo/
│   ├── sample_generator.py  # Synthetic marketing data
│   └── scenarios.py         # 4 curated demo scenarios
└── tools/
    ├── discovery/        # health_check, list_tables, describe_table, run_query
    ├── analysis/         # funnel, cac_ltv, retention, churn, anomalies
    ├── reports/          # growth_summary, executive, narrative, forecasting
    └── admin/            # profiles, connectors, attribution mapping

Key design decisions:

• Read-only enforcement — All SQL is validated by an AST parser (sqlglot) before execution. Any write, DDL, multi-statement, or PRAGMA operation is rejected.

• Demo-first — Every connector and every analysis runs on synthetic data with no configuration. Real credentials are optional.

• Benchmark context — Metrics are always compared to B2B SaaS median benchmarks (A16Z, OpenView) so raw numbers come with meaning.

• Structured output — All tools return ToolEnvelope objects rendered as clean markdown tables, not raw JSON blobs.

Test Suite

219 tests across 14 test files, covering unit tests, integration tests, and smoke tests.

pytest tests/ -q --tb=short
# 219 passed in ~8s

Test files

Real API connectivity tests

Connectors were tested against live APIs in development. Results:

Configuration Reference

All settings are environment variables (case-insensitive):

Core

Stripe

Meta Ads

Google Ads

HubSpot

Mixpanel

Amplitude

Docker

# Build
docker build -t growth-os .

# Demo mode (no credentials)
docker run -p 8000:8000 growth-os

# With CSV data
docker run -e GROWTH_DATA_DIR=/data -v /local/csv:/data growth-os

# With PostgreSQL
docker run -e POSTGRES_URL=postgresql://user:pass@host:5432/db growth-os

# With Stripe and HubSpot
docker run \
  -e STRIPE_API_KEY=sk_live_... \
  -e HUBSPOT_ACCESS_TOKEN=pat-eu1-... \
  growth-os

Limitations

• Read-only enforcement. GrowthOS enforces an AST-based SQL sandbox (sqlglot) that blocks any write, DDL, or multi-statement operation. You cannot accidentally modify data.

• Attribution is approximate. UTM-based attribution has known gaps: direct traffic, cross-device, and offline conversions are not captured.

• Forecasts are statistical, not causal. Linear and exponential smoothing forecasts extrapolate historical trends — they do not account for seasonality, planned campaigns, or market shocks. Use for directional guidance only.

• Benchmarks are medians. Industry benchmarks (B2B SaaS, A16Z, OpenView) reflect median-performing companies. Valid reasons to be above or below exist for every metric.

• Data freshness matters. Stale CSVs produce stale answers. Always run inspect_freshness before drawing conclusions from time-sensitive analyses.

• Connector demo mode produces synthetic data. Mock rows use fixed random seeds so output is deterministic and will not match your actual business metrics.

• HubSpot scope requirement. The Private App must have crm.objects.contacts.read and crm.objects.deals.read scopes. Without these scopes the connector returns HTTP 403 even with a valid token.

• Mixpanel free plan. The Funnels API returns HTTP 402 on free-tier projects. GrowthOS automatically falls back to synthetic funnel data in this case.

• Amplitude key types. Only the server-side API Key + Secret Key pair works for the Export API. The JavaScript SDK snippet key will not authenticate.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -q --tb=short

# Lint
python -m ruff check src/ tests/

# Verify server starts cleanly
python -c "from growth_os.app.server import create_mcp_server; create_mcp_server()"

Running the REST API in development

pip install -e ".[api]"
growth-os-api
# Swagger: http://localhost:8000/docs

Docs

• Product Roadmap

• Target Architecture

• Implementation TODO

License

MIT — see LICENSE.