Content
# Customer Health Analyzer MCP Server
An MCP (Model Context Protocol) server that provides AI-powered customer health analysis tools for GTM (Go-To-Market) teams. Analyzes customer usage, CRM, and support data to provide health scores and actionable recommendations.
## Features
- **AI-Powered Analysis**: Uses CrewAI agents with OpenAI GPT for intelligent customer health scoring
- **Comprehensive Scoring**: Analyzes usage, relationship, and support metrics
- **Actionable Recommendations**: Provides specific next steps with priorities and timelines
- **MCP Integration**: Works seamlessly with Claude Desktop and other MCP clients
- **Real-time Analysis**: Process customer data on-demand through MCP tools
- **Dynamic Data Sources**: Connects to HubSpot, Airtable, Zapier, or static data
- **🆕 Airtable Discovery**: Automatically discover all accessible bases and table schemas
- **🆕 Base Switching**: Easily switch between different Airtable bases with one command
- **🆕 Smart Table Detection**: AI-powered identification of customer data tables
## Architecture
### CrewAI Multi-Agent System
- **Data Integration Agents**: HubSpot, Airtable, Zapier specialists
- **Health Analysis Agent**: Calculates comprehensive health scores
- **AI Recommendation Agent**: Generates personalized action plans
- **Orchestrator**: Coordinates workflow and data synthesis
### Data Sources (Dynamic)
- **HubSpot CRM**: Contact data, deals, engagement metrics
- **Airtable**: Custom customer databases and usage tracking
- **Zapier**: Multi-platform data aggregation via webhooks
- **Static Data**: CSV files for demo/development
### Scoring Model
- **Usage Score (40%)**: Login frequency, session duration, feature adoption, usage trends
- **Relationship Score (30%)**: Contact recency, sentiment, contract status
- **Support Score (30%)**: Open tickets, resolution times, sentiment, escalations
### Health Status
- **Healthy** (80-100): Customer is engaged and satisfied
- **At Risk** (60-79): Customer needs attention to prevent churn
- **Critical** (0-59): Customer requires immediate intervention
## Installation
### 1. Clone the Repository
```bash
git clone https://github.com/tushar-badhwar/gtm-agent-user-health-analyzer.git
cd gtm-agent-user-health-analyzer
```
### 2. Setup Python Environment
**Option A: Using Virtual Environment (Recommended)**
```bash
# Create virtual environment
python3 -m venv venv
# Activate virtual environment
# Linux/macOS:
source venv/bin/activate
# Windows:
venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
```
**Option B: Using Conda**
```bash
# Create conda environment
conda create -n customer-health python=3.9
conda activate customer-health
# Install dependencies
pip install -r requirements.txt
```
**Option C: System-wide Installation**
```bash
# Install dependencies globally (not recommended for production)
pip install -r requirements.txt
```
### 3. Setup Environment Variables
```bash
# Copy environment template
cp .env.example .env
# Edit .env file and add your API keys
nano .env # or use your preferred editor
```
**Required environment variables:**
```bash
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini
# Optional - for Airtable integration
AIRTABLE_API_KEY=your_airtable_api_key_here
AIRTABLE_BASE_ID=your_airtable_base_id_here
```
### 4. Test the Installation
```bash
# Test the server starts correctly
python3 server.py
# You should see output like:
# 🚀 Customer Health Analyzer MCP Server starting...
# 💡 Server is ready to handle requests from Claude Desktop
```
If the server starts without errors, press `Ctrl+C` to stop it and proceed to configuration.
## Quick Start
### 1. Configure MCP Client
Add this server to your MCP client configuration (e.g., Claude Desktop):
#### For Windows with WSL:
```json
{
"mcpServers": {
"customer-health-analyzer": {
"command": "C:\\Windows\\System32\\wsl.exe",
"args": ["python3", "/home/tbadhwar/gtm-agent-user-health-analyzer/server.py"],
"env": {
"OPENAI_API_KEY": "your_openai_api_key_here",
"OPENAI_MODEL": "gpt-4o-mini",
"USE_STATIC_DATA": "true",
"DEFAULT_DATA_SOURCE": "static",
"AIRTABLE_API_KEY": "your_airtable_api_key_here",
"AIRTABLE_BASE_ID": "your_airtable_base_id_here"
}
}
}
}
```
#### For Linux/macOS:
```json
{
"mcpServers": {
"customer-health-analyzer": {
"command": "python3",
"args": ["/path/to/gtm-agent-user-health-analyzer/server.py"],
"env": {
"OPENAI_API_KEY": "your_openai_api_key_here",
"OPENAI_MODEL": "gpt-4o-mini",
"USE_STATIC_DATA": "true",
"DEFAULT_DATA_SOURCE": "static",
"AIRTABLE_API_KEY": "your_airtable_api_key_here",
"AIRTABLE_BASE_ID": "your_airtable_base_id_here"
}
}
}
}
```
### 2. Start the Server
```bash
# Start the MCP server
python3 server.py
# Server should start and show:
# 🚀 Customer Health Analyzer MCP Server starting...
# 💡 Server is ready to handle requests from Claude Desktop
# Keep this terminal open - the server must run while using Claude Desktop
```
### 3. Test with Claude Desktop
Once both the server is running and Claude Desktop is configured:
1. **Test data source switching:**
- "What data sources do I have available?"
- "Switch to static data and list all customers"
2. **Test customer analysis:**
- "Analyze the health of all customers"
- "Show me details for customer CUST001"
3. **Test recommendations:**
- "Give me recommendations for improving customer health"
## Available MCP Tools
### Core Customer Health Tools
#### 1. `set_data_source`
Select which data source to use for customer health analysis.
**Parameters:**
- `data_source` (required): "static", "airtable", "hubspot", or "zapier"
**Example:**
```
Use the set_data_source tool with data_source "airtable" to switch to your Airtable database
```
#### 2. `get_data_source_status`
Show current data source configuration and available options.
**Example:**
```
Use the get_data_source_status tool to see which data sources are configured
```
#### 3. `analyze_customer_health`
Analyze customer health scores for all customers or a specific customer from the currently selected data source.
**Parameters:**
- `customer_id` (optional): Specific customer ID to analyze (e.g., 'CUST001')
- `format` (optional): Output format - 'detailed' or 'summary' (default: 'detailed')
**Example:**
```
Use the analyze_customer_health tool to get a complete health analysis for all customers
```
#### 4. `list_customers`
List all available customers in the currently selected data source.
**Example:**
```
Use the list_customers tool to see what customers are available for analysis
```
#### 5. `get_customer_details`
Get detailed information about a specific customer.
**Parameters:**
- `customer_id` (required): Customer ID to get details for
**Example:**
```
Use the get_customer_details tool with customer_id "CUST001" to see detailed customer information
```
#### 6. `get_recommendations`
Get AI-powered recommendations for improving customer health.
**Parameters:**
- `customer_id` (required): Customer ID to get recommendations for
**Example:**
```
Use the get_recommendations tool with customer_id "CUST003" to get specific action items for this at-risk customer
```
### 🆕 Airtable Discovery & Management Tools
#### 7. `discover_airtable_bases`
Discover all accessible Airtable bases for the configured API token.
**Example:**
```
Use the discover_airtable_bases tool to see all your accessible Airtable bases
```
#### 8. `discover_airtable_schema`
Discover complete schema (tables and fields) for a specific Airtable base.
**Parameters:**
- `base_id` (required): Airtable base ID to analyze (e.g., 'appXXXXXXXXXXXXXX')
- `format` (optional): Output format - 'summary', 'detailed', or 'json'
**Example:**
```
Use the discover_airtable_schema tool with base_id "appXXXXXXXXXXXXXX" to analyze base structure
```
#### 9. `find_airtable_customer_tables`
Find tables in an Airtable base that likely contain customer data.
**Parameters:**
- `base_id` (required): Airtable base ID to analyze
**Example:**
```
Use the find_airtable_customer_tables tool with base_id "appXXXXXXXXXXXXXX" to find customer tables
```
#### 10. `connect_to_airtable_base`
🎯 **Key Feature**: Connect to a specific Airtable base - all subsequent operations will use this base.
**Parameters:**
- `base_id` (required): Airtable base ID to connect to
**Example:**
```
Use the connect_to_airtable_base tool with base_id "appXXXXXXXXXXXXXX" to switch to this base
```
#### 11. `get_current_airtable_base`
Show information about the currently connected Airtable base.
**Example:**
```
Use the get_current_airtable_base tool to check which base you're currently using
```
### Typical Workflow
1. **Discover bases**: `discover_airtable_bases` → See all available bases
2. **Connect to base**: `connect_to_airtable_base` → Switch to chosen base
3. **List customers**: `list_customers` → See customers in that base
4. **Analyze health**: `analyze_customer_health` → Get health scores
5. **Get recommendations**: `get_recommendations` → Get action items
## Sample Data
The server includes sample data for demonstration:
- **5 customers** with different health profiles:
- CUST001: TechCorp Inc (Healthy)
- CUST002: DataSolutions LLC (Healthy)
- CUST003: StartupXYZ (At Risk)
- CUST004: Enterprise Global (Healthy)
- CUST005: SmallBiz Co (Critical)
- **Usage data**: Login patterns, feature adoption, session durations
- **CRM data**: Contact history, sentiment, contract details
- **Support data**: Tickets, resolution times, sentiments
## Configuration
### Environment Variables
```bash
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini
# CRM Integration API Keys
HUBSPOT_API_KEY=your_hubspot_api_key_here
AIRTABLE_API_KEY=your_airtable_api_key_here
AIRTABLE_BASE_ID=your_airtable_base_id_here
ZAPIER_API_KEY=your_zapier_api_key_here
# Data Source Configuration
USE_STATIC_DATA=true # Set to false to use real CRM integrations
DEFAULT_DATA_SOURCE=static # static, hubspot, airtable, zapier
```
### Data Source Modes
**Static Mode (Default)**: Uses CSV demo data for testing
**Dynamic Mode**: Connects to real CRM systems via CrewAI agents
To switch to dynamic mode:
1. Add your CRM API keys to .env
2. Set `USE_STATIC_DATA=false`
3. Configure your preferred `DEFAULT_DATA_SOURCE`
## Example Usage with Claude Desktop
### 🆕 Enhanced Airtable Workflow
**Discover and Connect to Your Data:**
1. **"Show me all my Airtable bases"**
- Uses `discover_airtable_bases` tool
- Lists all accessible bases with IDs and names
2. **"Connect to my customer database (appXXXXXXXXXXXXXX)"**
- Uses `connect_to_airtable_base` tool
- Automatically analyzes base and recommends customer tables
- Switches all tools to use this base
3. **"What's in this base and which tables have customer data?"**
- Uses `discover_airtable_schema` tool for complete base analysis
- Uses `find_airtable_customer_tables` tool for smart table detection
### Classic Health Analysis Workflow
4. **"List all customers in the connected base"**
- Uses `list_customers` tool
- Shows customers from currently connected Airtable base
5. **"Analyze the health of all our customers"**
- Uses `analyze_customer_health` tool
- Returns comprehensive health scores and recommendations
6. **"Show me details for customer CUST003"**
- Uses `get_customer_details` tool
- Returns usage, CRM, and support data
7. **"What should we do to help our at-risk customers?"**
- Uses `analyze_customer_health` with summary format
- Provides prioritized action items
8. **"Give me specific recommendations for StartupXYZ"**
- Uses `get_recommendations` tool
- Returns AI-generated action plan
### Base Management
9. **"Which Airtable base am I currently using?"**
- Uses `get_current_airtable_base` tool
- Shows current base info and connection status
10. **"Switch to a different base for analysis"**
- Uses `connect_to_airtable_base` with new base ID
- All subsequent tools operate on new base
## Example Output
```
Customer Health Summary Report
================================
Total Customers Analyzed: 4
Average Health Score: 73.5/100
Health Status Distribution:
- Healthy: 2 customers (50.0%)
- At Risk: 1 customers (25.0%)
- Critical: 1 customers (25.0%)
StartupXYZ (ID: CUST003)
Health Score: 45/100 - At Risk
Detailed Scores:
- Usage: 30/100
- Relationship: 25/100
- Support: 70/100
Recommended Actions:
1. Schedule product training session
Priority: HIGH
Timeline: Within 1 week
Reasoning: Low usage indicates need for better product understanding
2. Schedule check-in call with CSM
Priority: HIGH
Timeline: Within 3 days
Reasoning: Poor relationship score indicates need for immediate outreach
```
## Project Structure
```
gtm-agent-user-health-analyzer/
├── server.py # Main MCP server
├── src/
│ ├── orchestrator.py # CrewAI workflow orchestrator
│ ├── agents/
│ │ ├── data_integration_agents.py # HubSpot, Airtable, Zapier agents
│ │ └── health_analysis_agents.py # Health scoring and recommendation agents
│ └── models/
│ └── customer_health.py # Pydantic models
├── data/
│ ├── sample_usage_data.csv # Sample usage metrics
│ ├── sample_crm_data.csv # Sample CRM data
│ └── sample_support_data.csv # Sample support data
├── requirements.txt # Python dependencies
├── pyproject.toml # Package configuration
├── mcp.json # MCP server configuration
├── .env.example # Environment template
└── README.md # This file
```
## Development
### Adding New Data Sources
To integrate with real CRM/support systems:
1. **Extend the `CustomerHealthAnalyzer` class** in `server.py`
2. **Add new collection methods** for your data sources
3. **Update scoring algorithms** as needed
4. **Add new MCP tools** for specific integrations
### Customizing Scoring
Modify the scoring methods in `server.py`:
- `calculate_usage_score()`
- `calculate_relationship_score()`
- `calculate_support_score()`
### Testing
```bash
# Install in development mode
pip install -e .
# Run the server
python server.py
# Test with MCP client or direct JSON-RPC calls
```
## Integration Roadmap
### Phase 2: Real Data Sources
- HubSpot CRM integration
- Salesforce integration
- Support system APIs (Zendesk, Intercom)
- Product analytics (Mixpanel, Amplitude)
### Phase 3: Advanced Features
- Predictive churn modeling
- Historical trend analysis
- Custom scoring models
- Automated alerting via MCP
## Troubleshooting
**Server won't start:**
- Check that all dependencies are installed: `pip install -r requirements.txt`
- Verify OPENAI_API_KEY is set in .env file or Claude Desktop config
- Ensure Python path is correct in MCP configuration
- For WSL: Verify `C:\\Windows\\System32\\wsl.exe` path is correct
**Tools disappear after usage:**
- This indicates server crashed due to unhandled exceptions
- Restart server: Stop (Ctrl+C) and run `python3 server.py` again
- Check server logs for error details
**No customer data:**
- Verify data files exist in `data/` directory
- Check file permissions and format
- Use `get_data_source_status` tool to verify configuration
- Use `set_data_source` tool to switch between static and Airtable
**Data inconsistency between tools:**
- All tools now use consistent data source routing
- Use `set_data_source` to change data source for all tools
- Restart server if switching between data sources
**AI recommendations not working:**
- Verify OPENAI_API_KEY is valid
- Check internet connectivity
- Server will fall back to rule-based recommendations if AI fails
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Feel free to use, modify, and distribute this software for any purpose.
---
Built with MCP, CrewAI, OpenAI GPT, and Python.
