telco-mcp-server

Telco Customer Churn MCP Server

An MCP (Model Context Protocol) server that exposes customer analytics and churn prediction capabilities to AI assistants like Claude Desktop. The server provides tools for data visualisation, correlation analysis, flexible querying, and machine learning predictions.

Overview

This project demonstrates how to build an MCP server that bridges AI assistants with data analysis and machine learning capabilities. It includes:

• Distribution plotting: generates visualisations for categorical and numerical columns
• Correlation analysis: creates heatmaps showing relationships between numerical features
• Flexible querying: filters data using natural language converted to pandas queries
• Churn prediction: uses a trained logistic regression model to assess customer retention risk

When Claude Desktop connects to this server, it can automatically call these tools to answer questions about customer behaviour, generate insights, and predict churn risk.

Features

• Natural language access to customer analytics through Claude Desktop
• Automatic chart generation (histograms for numerical data, bar charts for categories)
• Interactive data exploration using pandas query syntax
• ML-powered churn predictions with risk levels and recommendations
• Built with Python, pandas, scikit-learn, and the MCP SDK

Project Structure

telco-mcp-server/
├── data/
│   ├── telco_customer_churn.csv      # Original dataset
│   └── clean_data.csv                # Cleaned dataset for the server
├── html_export/
│   └── Telco Customer Churn MCP Server.ipynb  # HTML export of the jupyter notebook
├── notebooks/
│   └── Telco Customer Churn MCP Server.ipynb  # Main notebook
├── src/
│   └── server.py                     # MCP server implementation
├── start_server.bat                  # Batch script to launch the server
├── environment.yml                   # Conda environment specification
└── README.md

Prerequisites

• Python 3.11
• Conda (recommended) or pip
• Claude Desktop installed

Installation

1. Clone the repository

   git clone <repository-url>
   cd telco-mcp-server
   

2. Create the conda environment

   conda env create -f environment.yml
   conda activate mcp-analyst_py311
   

3. Run the notebook to generate clean data

   Open notebooks/Telco Customer Churn MCP Server.ipynb and run all cells to create data/clean_data.csv. Edit the src/server.py file to set the correct path to clean_data.csv.

4. Configure Claude Desktop

   Edit your Claude Desktop configuration file:

   Location: %APPDATA%\Claude\claude_desktop_config.json

   Add this entry to the mcpServers section:

   {
     "mcpServers": {
       "telco-analyst": {
         "command": "cmd.exe",
         "args": [
           "/c",
           "C:\\path\\to\\telco-mcp-server\\start_server.bat"
         ]
       }
     }
   }
   

   Replace C:\\path\\to\\telco-mcp-server with the actual path to your project folder.

5. Restart Claude Desktop

   The MCP server will start automatically when Claude Desktop launches.

Usage

Once configured, open Claude Desktop and ask questions that trigger the tools:

Example Queries

Query Type	Example
Distribution plotting	“Show me the distribution of MonthlyCharges”
Correlation analysis	“What’s the correlation between tenure and churn?”
Data filtering	“Show me senior citizens paying over £70 per month”
Churn prediction	“Predict churn risk for a customer with: Female, not a senior citizen, tenure of 3 months, fibre optic internet, month-to-month contract, monthly charges £85”

Claude will automatically call the appropriate MCP tools and return results with visualisations, data summaries, or predictions.

Available Tools

plot_distribution

Generates distribution visualisations for any column in the dataset. Automatically selects bar charts for categorical data or histograms for numerical data.

get_correlation_matrix

Creates a heatmap showing Pearson correlations between all numerical features, useful for understanding relationships between variables like tenure, charges, and churn.

run_pandas_query

Filters the dataset using pandas query syntax. Supports complex conditions like "SeniorCitizen == 'Yes' and MonthlyCharges > 70".

predict_churn

Predicts churn probability for a customer based on 19 input features. Returns:

• Churn probability percentage
• Risk level (Low/Medium/High)
• Actionable business recommendation

Data Source

Telco Customer Churn Dataset

A telecommunications dataset containing 7,043 customers with 21 features covering:

• Demographics: gender, senior citizen status, partner, dependents
• Services: phone service, internet type, streaming services, security features
• Contract details: tenure, contract type, billing method, payment method
• Charges: monthly charges, total charges
• Outcome: churn status (customer left or stayed)

Source: Kaggle - Telco Customer Churn

References

• Model Context Protocol (MCP)
• MCP Python SDK
• Telco Customer Churn Dataset
• Claude Desktop
• scikit-learn Logistic Regression

Licence

This project is for educational purposes.