gtm-agent-user-health-analyzer by tushar-badhwar - MCP Server

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

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)

# 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

# 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

# Install dependencies globally (not recommended for production)
pip install -r requirements.txt

3. Setup Environment Variables

# 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:

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

# 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:

{
  "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:

{
  "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

# 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:

Test data source switching:
- "What data sources do I have available?"
- "Switch to static data and list all customers"
Test customer analysis:
- "Analyze the health of all customers"
- "Show me details for customer CUST001"
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

Discover bases: discover_airtable_bases → See all available bases
Connect to base: connect_to_airtable_base → Switch to chosen base
List customers: list_customers → See customers in that base
Analyze health: analyze_customer_health → Get health scores
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

# 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:

Add your CRM API keys to .env
Set USE_STATIC_DATA=false
Configure your preferred DEFAULT_DATA_SOURCE

Example Usage with Claude Desktop

🆕 Enhanced Airtable Workflow

Discover and Connect to Your Data:

"Show me all my Airtable bases"
- Uses discover_airtable_bases tool
- Lists all accessible bases with IDs and names
"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
"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

"List all customers in the connected base"
- Uses list_customers tool
- Shows customers from currently connected Airtable base
"Analyze the health of all our customers"
- Uses analyze_customer_health tool
- Returns comprehensive health scores and recommendations
"Show me details for customer CUST003"
- Uses get_customer_details tool
- Returns usage, CRM, and support data
"What should we do to help our at-risk customers?"
- Uses analyze_customer_health with summary format
- Provides prioritized action items
"Give me specific recommendations for StartupXYZ"
- Uses get_recommendations tool
- Returns AI-generated action plan

Base Management

"Which Airtable base am I currently using?"
- Uses get_current_airtable_base tool
- Shows current base info and connection status
"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:

Extend the CustomerHealthAnalyzer class in server.py
Add new collection methods for your data sources
Update scoring algorithms as needed
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

# 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 file for details.

Feel free to use, modify, and distribute this software for any purpose.

Built with MCP, CrewAI, OpenAI GPT, and Python.

tushar-badhwar/gtm-agent-user-health-analyzer

Customer Health Analyzer MCP Server

Features

Architecture

CrewAI Multi-Agent System

Data Sources (Dynamic)

Scoring Model

Health Status

Installation

1. Clone the Repository

2. Setup Python Environment

3. Setup Environment Variables

4. Test the Installation

Quick Start

1. Configure MCP Client

For Windows with WSL:

For Linux/macOS:

2. Start the Server

3. Test with Claude Desktop

Available MCP Tools

Core Customer Health Tools

1. set_data_source

2. get_data_source_status

3. analyze_customer_health

4. list_customers

5. get_customer_details

6. get_recommendations

🆕 Airtable Discovery & Management Tools

7. discover_airtable_bases

8. discover_airtable_schema

9. find_airtable_customer_tables

10. connect_to_airtable_base

11. get_current_airtable_base

Typical Workflow

Sample Data

Configuration

Environment Variables

Data Source Modes

Example Usage with Claude Desktop

🆕 Enhanced Airtable Workflow

Classic Health Analysis Workflow

Base Management

Example Output

Project Structure

Development

Adding New Data Sources

Customizing Scoring

Testing

Integration Roadmap

Phase 2: Real Data Sources

Phase 3: Advanced Features

Troubleshooting

License

1. `set_data_source`

2. `get_data_source_status`

3. `analyze_customer_health`

4. `list_customers`

5. `get_customer_details`

6. `get_recommendations`

7. `discover_airtable_bases`

8. `discover_airtable_schema`

9. `find_airtable_customer_tables`

10. `connect_to_airtable_base`

11. `get_current_airtable_base`