GDAL MCP Server

GDAL MCP

Geospatial AI with epistemic reasoning

GDAL MCP is a Model Context Protocol (MCP) server that provides AI agents with geospatial analysis capabilities while requiring them to justify their methodological choices through a reflection middleware system.

🎉 v1.1.1 Released (2025-10-26) — Vector tool parity + cross-domain reflection validated
🧠 Reflection System — Domain-based epistemic reasoning that transcends data types
⚡ 75% Cache Hit Rate — Methodology reasoning carries across raster ↔ vector operations

📚 Documentation

• Quick Start - Installation, setup, and MCP configuration
• Tools Reference - Complete tool documentation with examples
• Environment Variables - Runtime configuration and tool surface controls
• Vision - Long-term roadmap and philosophy
• Changelog - Release history and updates

🧠 The Reflection System

What Makes GDAL MCP Different?

Most AI tool systems execute operations immediately when requested. GDAL MCP requires the AI to justify methodological decisions before execution, creating a conversation about the "why" rather than just executing the "what."

Traditional AI tool approach:

User: "Reproject this DEM to Web Mercator"
AI: *silently executes operation*
Result: DEM reprojected (but with what resampling? why that CRS? what tradeoffs?)

GDAL MCP with reflection:

User: "Reproject this DEM to Web Mercator for my web map"
AI: *reflection middleware intercepts*
AI: "Before reprojecting to EPSG:3857, let me justify this CRS choice:
     
     Intent: Web Mercator preserves angles (conformal projection),
             essential for web tile rendering and navigation
     
     Alternatives considered:
     - EPSG:4326 (WGS84) → rejected: not conformal, distorts shapes
     - Local UTM → rejected: limited extent, not web-standard
     
     Tradeoffs: Area distortion increases at high latitudes
                (acceptable for web visualization)
     
     Confidence: High - this is the standard for web mapping"

*justification stored, operation proceeds*
Result: DEM reprojected with documented methodology

Why This Matters

1. Utilizes Full MCP Protocol Capabilities

The Model Context Protocol isn't just about tool execution—it's about agentic reasoning and interaction. The reflection system leverages MCP's design to enable:

• Pre-execution prompting (tool dependencies)
• Structured reasoning (schema-validated justifications)
• Stateful workflows (justification caching)
• Human-in-the-loop interaction (advisory prompts)

2. Prevents Silent Failures

Geospatial operations can execute successfully while producing methodologically incorrect results:

• Nearest-neighbor resampling on continuous elevation data (creates artifacts)
• Web Mercator for area calculations (40%+ distortion possible)
• Bilinear interpolation on categorical data (creates invalid class values)

The reflection system surfaces these choices for validation.

3. Educational, Not Restrictive

The AI isn't blocked from executing operations—it's required to demonstrate understanding:

• First use: Explains reasoning, teaches methodology
• Cached: Instant execution (knowledge persists)
• Result: 75%+ cache hit rates, minimal friction

4. Creates Audit Trail

Every methodological decision is documented with:

• Intent (what property must be preserved?)
• Alternatives (what else was considered?)
• Rationale (why this choice?)
• Tradeoffs (what are the limitations?)
• Confidence (high/medium/low)

This enables reproducible geospatial science.

🎯 Example Workflow

Multi-Operation Geospatial Analysis

User: "I need to reproject this DEM to UTM for accurate slope analysis,
       then reproject this vector layer to the same CRS for overlay"

AI Workflow:
1. Inspects DEM metadata (raster_info)
2. REFLECTION: Justifies UTM Zone 10N choice (accurate distance/area)
3. REFLECTION: Justifies cubic resampling (smooth gradients for derivatives)
4. Reprojects DEM (raster_reproject)
5. Inspects vector metadata (vector_info)
6. CACHE HIT: Reuses UTM justification (cross-domain!)
7. Reprojects vector (vector_reproject) - instant, no re-prompting
8. Both