customer-retention-ltv-mcp 0.1.0

Customer Retention & LTV Intelligence MCP

Customer Retention & LTV Intelligence MCP

Core Problem

Brands scale campaigns that look profitable on first purchase but destroy long-term unit economics.

What This Server Provides

This folder contains a production-minded MCP server scaffold with typed JSON tool responses, connector health metadata, OAuth-oriented configuration, rate-limit guards, stable error envelopes, and deterministic demo data until live vendor integrations are attached.

This server has received a production pass. It now includes local customer economics models for acquisition-channel LTV, gross-profit payback, churn-risk segmentation, repurchase cohorts, lifecycle flow performance, safe winback staging, and best-segment discovery.

Connectors

• Shopify Admin API via OAuth scope read_customers; env prefix SHOPIFY
• Klaviyo API via OAuth scope profiles:read; env prefix KLAVIYO
• Postscript API via OAuth scope sms.read; env prefix POSTSCRIPT
• Yotpo Loyalty API via OAuth scope loyalty.read; env prefix YOTPO
• Google Ads API via OAuth scope adwords.readonly; env prefix GOOGLE_ADS
• Meta Ads API via OAuth scope ads_read; env prefix META_ADS

MCP Tools

• get_ltv_by_channel - LTV by acquisition source over a configurable window.
• get_churn_risk_segment - Customers most likely to lapse.
• get_repurchase_rate_by_channel - Cohort repurchase rates by source.
• get_email_flow_performance - Revenue per recipient and drop-off.
• trigger_winback_campaign - Safely queue a win-back flow action.
• get_best_performing_segments - Highest-LTV customer profiles and traits.

Current Local Capabilities

• Calculates LTV, gross-profit LTV, LTV:CAC, profit after CAC, and repurchase rate by channel.
• Finds high, medium, and low churn-risk lifecycle segments.
• Computes repurchase rate and revenue per customer for monthly cohorts.
• Reports email flow open, click, order, and revenue-per-recipient metrics.
• Stages winback campaigns for approval instead of sending automatically.
• Blocks low-risk customers from winback campaigns through a policy guardrail.
• Identifies best customer traits for acquisition and retention planning.

Test

python -m pytest .\tests -q -p no:cacheprovider

Partial Platform Support

Customers only need to connect the retention platforms they actually use. Missing Shopify, Klaviyo, Postscript, Yotpo, Google Ads, or Meta Ads credentials do not prevent the server from starting or running local intelligence tools.

Use get_live_connector_status to see configured connectors. Use test_shopify_retention_connection and test_klaviyo_connection for read-only live smoke checks when those platforms are connected.

Running Locally

powershell python -m venv .venv .\.venv\Scripts\pip install -e . .\.venv\Scripts\python -m customer_retention_ltv_mcp.server

Claude Desktop Config

json { "mcpServers": { "customer-retention-ltv": { "command": "python", "args": ["-m", "customer_retention_ltv_mcp.server"], "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\04-customer-retention-ltv" } } }

Production Checklist

• Create OAuth 2.1 apps for each connector and set *_CLIENT_ID plus *_CLIENT_SECRET.
• Store refresh tokens in a secrets manager, never in repo files.
• Replace deterministic demo rows in server.py with API adapter calls.
• Persist raw snapshots and normalized warehouse tables for trend analysis.
• Add integration tests with recorded fixtures for every connector.
• Validate every tool in MCP Inspector before publishing.
• Deploy with a /health route through FastMCP streamable HTTP on Railway or Render.