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.
Evaluated against WRI Aqueduct ground truth across 3 climate indicators and 20 gold-case queries.
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
| 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 |
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 |
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 |
Normalizes geographic names to internal IDs β handles aliases, historical names, ISO-2/ISO-3 codes, and common misspellings.
Semantic vector search (pgvector) across climate documentation, methodology papers, and indicator metadata.
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β
| 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 |
[ 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
mcp_climate/β Core FastAPI MCP server with tool registry, chat endpoint, and rate limitingdatabase/β PostgreSQL ETL pipeline ingesting Aqueduct datasets intocoreandvectorschemastesting/β Containerized benchmark suite with gold-case evaluation and ground truth validation
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
- Docker & Docker Compose v2.0+
- Python 3.11+ (for local development)
# 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:8000PYTEST_TARGET=tests/test_health.py \
docker compose --profile testing up --build --abort-on-container-exitdocker compose --profile testing up --build --abort-on-container-exitResults are written to testing/results/ as JSON artifacts with full tool call traces.
| 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 |
| 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 |
Aditya Indurkhya
Master of Science in Data Analytics Engineering | B.Tech in Computer Science Engineering





