Skip to content

About

AI-powered climate intelligence system using MCP tools, RAG pipelines, and LLMs to answer climate risk queries. Benchmarked on 20 gold cases with 70% accuracy across BWS, RFR, and DRR indicators.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🌍 ClimateGPT

MCP Server for Climate Risk Intelligence

An AI-powered climate risk analysis platform built on the Model Context Protocol

Query water stress, flood risk, and drought indicators across 180+ countries using natural language β€” powered by the WRI Aqueduct Water Risk Atlas and a pgvector semantic search engine.


Python FastAPI PostgreSQL Docker MCP pgvector


Accuracy Cases Latency Countries


πŸ“Έ Benchmark Results & Visuals

System Architecture

Architecture


MCP Tool Suite

MCP Tools


Benchmark Accuracy by Indicator

Evaluated against WRI Aqueduct ground truth across 3 climate indicators and 20 gold-case queries.

Benchmark Accuracy


Overall Accuracy Summary

Benchmark Summary


API Response Latency Distribution

Latency Distribution


Per-Query Results & Latency

Per Query Results


🧠 What is ClimateGPT?

ClimateGPT is a Model Context Protocol (MCP) server that exposes structured climate intelligence tools to LLM agents. It bridges natural language queries with the WRI Aqueduct Water Risk Atlas β€” one of the world's most comprehensive open climate datasets β€” enabling AI systems to answer precise, data-grounded questions about water stress, flood risk, and drought across any geography.

The platform is designed for:

  • AI agents that need reliable climate data retrieval
  • Researchers querying climate indicators programmatically
  • Developers building climate-aware applications on top of MCP

⚑ Key Capabilities

Capability Description
Structured Retrieval SQL-backed queries for exact indicator values, trends, rankings, and scenario comparisons
Multi-Scenario Analysis Compare baseline vs. RCP 4.5 / RCP 8.5 climate projections
Geographic Intelligence Resolves ambiguous names (e.g. "Bombay" β†’ "Mumbai", ISO-2 β†’ ISO-3)
Semantic Search pgvector-powered search across climate documentation and metadata
Benchmarked Accuracy 70% accuracy on 20 gold-case queries against WRI Aqueduct ground truth
100+ Gold Cases Full evaluation suite with expected scores and tolerance thresholds

πŸ”§ MCP Tools

query_structured_data

Direct SQL-backed retrieval for specific geographic climate indicators.

Supported operations:

Operation Description
value Retrieve a specific indicator value for a geography
trend Get historical trend data across time periods
compare_geographies Side-by-side comparison of multiple countries/regions
rank_geographies Rank countries by indicator score (top N)
compare_scenarios Compare baseline vs. future climate scenarios
distribution Get global distribution of an indicator
hierarchy Retrieve geographic hierarchy (country β†’ basin β†’ sub-basin)
children List child geographies of a parent region

analyze_climate_risk

High-level multi-indicator risk analysis combining structured data and semantic context.

Supported operations:

Operation Description
summary Comprehensive risk summary for a location
region_risk Detailed risk profile for a specific indicator
compare_regions Multi-region risk comparison
explain_trend Contextual explanation of risk trends

resolve_entities

Normalizes geographic names to internal IDs β€” handles aliases, historical names, ISO-2/ISO-3 codes, and common misspellings.

retrieve_knowledge

Semantic vector search (pgvector) across climate documentation, methodology papers, and indicator metadata.


πŸ“Š Benchmark Results

Evaluated on 20 gold-case queries against WRI Aqueduct ground truth data:

Indicator Cases Correct Accuracy Avg Latency
Baseline Water Stress (BWS) 7 4 57.1% 5.88s
Riverine Flood Risk (RFR) 7 5 71.4% 6.78s
Drought Risk (DRR) 6 5 83.3% 6.07s
Overall 20 14 70.0% 6.25s

Ground truth sourced from aqueduct_ground_truth.csv β€” WRI Aqueduct v4.0 country-level aggregates.

Sample verified queries:

  • "What is the baseline water stress score for Iran?" β†’ Extracted: 4.679 | Expected: 4.679 βœ…
  • "What is the riverine flood risk score for Cambodia?" β†’ Extracted: 4.461 | Expected: 4.461 βœ…
  • "What is the drought risk score for Tunisia?" β†’ Extracted: 3.483 | Expected: 3.483 βœ…

πŸ—„οΈ Data Sources

Dataset Version Coverage Indicators
WRI Aqueduct Water Risk Atlas v4.0 180+ countries BWS, RFR, DRR, and 13 more
WRI Aqueduct Projections v3.0 Global basins RCP 4.5, RCP 8.5 scenarios
Basin Studies Colorado, Mekong, Yangtze Regional Detailed hydrological data
Corporate Water Risk TCCC Site-level Operational water risk
Global Flood Risk 2015 Country/State/Basin Flood exposure metrics

πŸ—οΈ Architecture

                          [ User / LLM Client ]
                                   |
                                   v
                       +-----------------------+
                       |      MCP Server       |
                       |  (FastAPI + Protocol) |
                       |    Chat UI (Static)   |
                       +-----------+-----------+
                                   |
         +-------------------------+-------------------------+
         |                         |                         |
[ ClimateGPT API ]      [ PostgreSQL Warehouse ]   [ Benchmarking Suite ]
  LLM Intelligence        Aqueduct + pgvector         100+ Gold Cases
         |                         |                         |
         v                         v                         v
  query_structured_data    Geography Service         test_health.py
  analyze_climate_risk     Indicator Service         test_mcp_benchmark.py
  resolve_entities         Vector DB (pgvector)      test_aqueduct_benchmark.py
  retrieve_knowledge       Document Service

Services

  • mcp_climate/ β€” Core FastAPI MCP server with tool registry, chat endpoint, and rate limiting
  • database/ β€” PostgreSQL ETL pipeline ingesting Aqueduct datasets into core and vector schemas
  • testing/ β€” Containerized benchmark suite with gold-case evaluation and ground truth validation

πŸ“‚ Repository Structure

ClimateGPT/
β”‚
β”œβ”€β”€ mcp_climate/                  # MCP Server
β”‚   └── app/
β”‚       β”œβ”€β”€ api/
β”‚       β”‚   β”œβ”€β”€ chat.py           # OpenAI-compatible chat endpoint
β”‚       β”‚   └── tools.py          # Tool schema + execution endpoints
β”‚       β”œβ”€β”€ mcp/tools/
β”‚       β”‚   β”œβ”€β”€ query_structured_data.py
β”‚       β”‚   β”œβ”€β”€ analyze_climate_risk.py
β”‚       β”‚   β”œβ”€β”€ resolve_entities.py
β”‚       β”‚   └── retrieve_knowledge.py
β”‚       └── services/
β”‚           β”œβ”€β”€ geography_service.py
β”‚           β”œβ”€β”€ indicator_service.py
β”‚           β”œβ”€β”€ vector_db.py
β”‚           └── analysis_service.py
β”‚
β”œβ”€β”€ database/                     # ETL Pipeline
β”‚   β”œβ”€β”€ extractors/               # Aqueduct, Excel, PDF, Spatial parsers
β”‚   β”œβ”€β”€ create_database.sql       # Full schema (core + vector namespaces)
β”‚   β”œβ”€β”€ main_loader.py            # CLI ingestion entry point
β”‚   └── vector_loader.py          # pgvector embedding hydration
β”‚
β”œβ”€β”€ testing/                      # Evaluation Suite
β”‚   β”œβ”€β”€ fixtures/
β”‚   β”‚   β”œβ”€β”€ gold_cases_aqueduct.json   # 100+ benchmark questions
β”‚   β”‚   └── aqueduct_ground_truth.csv  # Expected scores
β”‚   β”œβ”€β”€ tests/
β”‚   β”‚   β”œβ”€β”€ test_health.py             # CI connectivity check
β”‚   β”‚   └── test_mcp_benchmark.py      # Full benchmark runner
β”‚   └── results/                       # JSON benchmark artifacts
β”‚
β”œβ”€β”€ screenshots/                  # Portfolio visuals
β”œβ”€β”€ docker-compose.yml            # Full stack (db + mcp + evaluator)
β”œβ”€β”€ docker-compose.db.yml         # Database only
β”œβ”€β”€ docker-compose.mcp.yml        # MCP server only
β”œβ”€β”€ docker-compose.evaluator.yml  # Evaluator only
β”œβ”€β”€ Makefile                      # Dev task runner
└── .env.example                  # Environment template

πŸš€ Getting Started

Prerequisites

  • Docker & Docker Compose v2.0+
  • Python 3.11+ (for local development)

Quick Start (Full Stack)

# 1. Clone and configure
git clone https://github.com/Adityaindurkhya/ClimateGPT.git
cd ClimateGPT
cp .env.example .env

# 2. Start database + MCP server
docker compose up -d db mcp

# 3. Open the Chat UI
# http://localhost:8000

Run Connectivity Tests (Fast CI)

PYTEST_TARGET=tests/test_health.py \
  docker compose --profile testing up --build --abort-on-container-exit

Run Full Benchmark Suite

docker compose --profile testing up --build --abort-on-container-exit

Results are written to testing/results/ as JSON artifacts with full tool call traces.


🐳 Docker Commands

Action Command
Setup cp .env.example .env
Start DB + MCP docker compose up -d db mcp
Run All Tests docker compose --profile testing up --build --abort-on-container-exit
View Logs docker compose logs -f
Stop All docker compose down
Full Clean docker compose down -v

πŸ› οΈ Tech Stack

Category Technologies
Server FastAPI, Python 3.11, Uvicorn
Protocol Model Context Protocol (MCP)
Database PostgreSQL 15, pgvector, SQLAlchemy
Data WRI Aqueduct v4.0, GeoDataFrames, Shapefiles
ETL Pandas, GeoPandas, PyPDF2, OpenPyXL
Embeddings pgvector semantic search
Testing pytest, Docker Compose profiles
CI/CD GitHub Actions
Infra Docker, Docker Compose, Makefile

πŸ‘¨β€πŸ’» Author

Aditya Indurkhya

Master of Science in Data Analytics Engineering | B.Tech in Computer Science Engineering

GitHub

About

AI-powered climate intelligence system using MCP tools, RAG pipelines, and LLMs to answer climate risk queries. Benchmarked on 20 gold cases with 70% accuracy across BWS, RFR, and DRR indicators.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages