🏦 AI-Powered Customer Intelligence PoC

Claude + Teradata ClearScape Analytics via Model Context Protocol (MCP)

---

What Is This?

This project demonstrates how Claude AI can be connected directly to Teradata to enable:

🔍 Natural language data exploration — Ask Claude about your data in plain English
🤖 In-database ML — Run KMeans clustering inside Teradata via Claude, no data movement
📊 Progressive segmentation — Show how richer features reveal richer customer segments
🔗 MCP as a data engineering framework — A reusable pattern for AI + enterprise data

---

The Business Story

"We started with 50,000 customers and 2 years of transactions. By asking Claude natural language questions, we profiled our data, identified quality issues, and ran customer segmentation — all without writing a single line of SQL manually. Everything ran inside Teradata. No data left the platform."

Three Phases of Segmentation

| Phase | Features Used | What It Reveals | |---|---|---| | 1. Behavioral | RFM (Recency, Frequency, Monetary) | How customers transact | | 2. + Risk | RFM + Credit Score | Who is financially at-risk | | 3. + Demographics | RFM + Risk + Age + Income | Full customer identity |

Each phase finds a different optimal number of clusters — proving that richer data = richer insight.

---

Architecture

┌─────────────────────────────────────────────────────┐
│                  Claude Desktop                      │
│          (Natural Language Interface)                │
└────────────────────┬────────────────────────────────┘
                     │ MCP Protocol
┌────────────────────▼────────────────────────────────┐
│              MCP Server (server.py)                  │
│   13 Tools: query, profile, skew, PI, KMeans...     │
└────────────────────┬────────────────────────────────┘
                     │ teradatasql
┌────────────────────▼────────────────────────────────┐
│         Teradata ClearScape Analytics                │
│   transactions │ demographics │ credit_risk          │
│   segmentation_*_scaled │ val.tda_kmeans             │
└─────────────────────────────────────────────────────┘

---

Project Structure

teradata-mcp-poc/
│
├── config.example.yaml        ← Copy this → config.yaml and add credentials
├── requirements.txt           ← Python dependencies
│
├── mcp/
│   └── server.py              ← MCP server (15 tools for Teradata)
│
├── notebooks/
│   └── 01_poc_walkthrough.ipynb  ← Full PoC narrative (run this first)
│
├── scripts/
│   └── kmeans_experiment.py   ← Standalone Python experiment runner
│
└── docs/
    └── mcp_tools_reference.md ← All 15 MCP tools explained

---

Quick Start

Prerequisites

Python 3.11+
Claude Desktop (download here)
Teradata ClearScape account (free trial)

1. Clone the repo

git clone https://github.com/YOUR_USERNAME/teradata-mcp-poc.git
cd teradata-mcp-poc

2. Install dependencies

pip install -r requirements.txt

3. Configure credentials

cp config.example.yaml config.yaml
# Edit config.yaml with your Teradata host, username, and password

4. Connect Claude Desktop to Teradata

Add this to your Claude Desktop config file:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "teradata": {
      "command": "python",
      "args": ["C:\\path\\to\\teradata-mcp-poc\\mcp\\server.py"]
    }
  }
}

Restart Claude Desktop — you'll see teradata appear in Settings → Connectors.

5. Talk to your data

Open Claude Desktop and ask: `` List all my Teradata databases Show me the tables in demo_user Profile the transactions table Check for data skew on the customer_demographics table Run a data quality check on demo_user.credit_risk ``

6. Run the notebook

jupyter notebook notebooks/01_poc_walkthrough.ipynb

---

MCP Tools Reference

| Tool | What it does | |---|---| | run_sql | Execute any Teradata SQL | | list_databases | Show all accessible databases | | list_tables | Show tables in a database | | get_schema | Column definitions via DBC.ColumnsV | | get_table_ddl | Full CREATE TABLE statement | | profile_table | Row count, nulls, distinct values, size | | check_duplicates | Find duplicate rows on key columns | | get_table_stats | Optimizer statistics (COLLECT STATS) | | check_data_skew | AMP distribution analysis | | get_pi_info | Primary Index definition | | find_table_references | Views/macros that use a table | | export_to_csv | Save query results to CSV | | get_space_usage | Perm space usage per database | | run_kmeans_experiment | Elbow analysis for k=2..N | | run_kmeans_final | Save final KMeans model to table |

---

Example Conversations with Claude

Data exploration: > "Profile the transactions table and tell me if there are any data quality issues"

Segmentation: > "Run a KMeans experiment on segmentation_rfm_scaled using monetary_scaled, frequency_scaled, recency_scaled for k=2 to 8"

Performance: > "Check if the customer_demographics table has any skew issues and review its Primary Index"

Lineage: > "Find everything that references the transactions table"

---

Dataset

The PoC uses a synthetic customer dataset with:

799,477 transactions across 50,000 customers (Jan 2023 – Dec 2024)
Customer demographics: age, income, employment years
Credit risk: credit score (400–849), loan exposure, late payments
Pre-built features: RFM aggregations, multiple scaled tables for clustering

---

Tech Stack

| Component | Technology | |---|---| | AI Interface | Claude Desktop | | AI ↔ Data Protocol | MCP (Model Context Protocol) | | Database | Teradata ClearScape Analytics | | In-Database ML | Teradata VAL (val.tda_kmeans) | | Python ML | teradataml, scikit-learn | | Visualization | matplotlib, seaborn |

---

License

MIT — free to use and adapt for your own PoC.

---

Built with Claude Desktop + Teradata ClearScape Analytics

teradata-mcp-poc