by Wayfinder-Foundry
Packages GDAL‑style geospatial workflows with Python‑native libraries (Rasterio, GeoPandas, PyProj, etc.) and adds AI‑agent‑driven catalog discovery, metadata intelligence, and raster/vector processing backed by epistemic reasoning.
Gdal Mcp provides a Model Context Protocol (MCP) server that lets AI agents execute geospatial operations while justifying methodological choices such as CRS selection and resampling methods. The server wraps rasterio, pyproj, pyogrio, shapely and related libraries, exposing tools for raster info, conversion, reprojection, statistics, and vector inspection, all governed by a reflection middleware that caches justifications for repeatable, scientifically‑rigorous workflows.
uvx (or Docker/local dev) and run the server with the stdio transport.
uvx --from gdal-mcp gdal --transport stdio
raster_info, raster_reproject) with the required parameters in JSON. The reflection layer automatically prompts for justification when needed, stores it, and proceeds with execution.uvx run.Q: Do I need to supply justification manually?
A: No. The reflection middleware automatically generates a structured justification the first time a methodological parameter (e.g., CRS, resampling) is used. You can view or store it via store_justification.
Q: Can I disable the reflection system? A: The server is designed around reflection; disabling it would require custom middleware modifications.
Q: Which resampling methods are supported?
A: nearest, bilinear, cubic, lanczos – each triggers a justification appropriate to the data type.
Q: How does caching work across sessions?
A: Justifications are written to .preflight/justifications/{domain}/sha256:{hash}.json. They persist on disk and are reused by any subsequent request on the same server instance.
Q: What Python version is required? A: Python 3.11 or newer.
Q: Is the server compatible with Claude Desktop?
A: Yes. Add a configuration entry pointing to the uvx command as shown in the README.
The first geospatial AI substrate with epistemic reasoning
"Before reprojecting to EPSG:3857, why is this CRS appropriate for your analysis? What spatial properties must be preserved? What distortion tradeoffs are acceptable?"
GDAL MCP doesn't just execute geospatial operations—it thinks through them. Built on FastMCP with a reflection middleware that requires AI agents to justify methodological decisions before execution.
🎉 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
Geospatial operations have consequences. Choosing the wrong resampling method can introduce false elevation data. Selecting an inappropriate CRS can distort area calculations by 40%. Aggregating without understanding data distribution can hide critical outliers.
Traditional approach:
User: "Reproject this DEM to Web Mercator"
AI: *immediately executes gdal.Warp()*
GDAL MCP with reflection:
User: "Reproject this DEM to Web Mercator for a web map"
AI: *triggered to justify CRS choice*
"Before reprojecting to EPSG:3857:
- Intent: Preserve angular relationships for web tile rendering
- Alternatives considered: EPSG:4326 (rejected: not conformal)
- Tradeoffs: Distance/area distortion at high latitudes acceptable for visualization
- Confidence: High"
*stores justification, proceeds with operation*
The AI doesn't just follow instructions—it understands the methodology.
Scenario: You need to reproject a 30m elevation model from WGS84 to UTM for slope analysis.
User prompt:
Reproject my DEM from test/data/elevation.tif to UTM Zone 10N.
I need accurate slope calculations.
What happens:
raster_info reveals EPSG:4326, 30m resolutionCache behavior: Next time you reproject any DEM to UTM with cubic, no re-justification needed.
User prompt:
Create a Cloud-Optimized GeoTIFF from this 10GB Landsat scene.
Optimize for web serving with multiple zoom levels.
What happens:
Building overviews [2, 4, 8, 16]...
Output: 1.2GB (88% reduction)
Validation: ✓ COG structure valid
First request:
Reproject this imagery to EPSG:3857 using cubic resampling for a web map.
→ Triggers both CRS and resampling justifications (~30 seconds)
Second request (same session):
Now reproject this other tile to EPSG:3857 with cubic for the same map.
→ Cache hit! Both justifications reused (instant)
Third request (different parameter):
Actually, use bilinear instead to reduce processing time.
→ CRS justification cached, only resampling re-justified
The core innovation: FastMCP middleware that intercepts tool calls and enforces epistemic discipline.
.preflight/justifications/{domain}/) with SHA256-based lookupReflection domains:
crs_datum — Coordinate system selection and datum transformationsresampling — Interpolation method choice for raster operationshydrology — Flow direction, watershed delineation, DEM conditioning (planned)aggregation — Zonal statistics, temporal composites, data fusion (planned)How it works:
raster_reproject call, checks cachejustify_crs_selection promptSee: test/REFLECTION_TESTING.md for comprehensive testing guide with 7 scenarios
catalog://workspace/{all|raster|vector}/{subpath} for autonomous planningmetadata://{file}/format for driver/format detailsreference://crs/common/{coverage})# Run directly without installation
uvx --from gdal-mcp gdal --transport stdio
# Build and run
docker build -t gdal-mcp .
docker run -i gdal --transport stdio
# Clone and install
git clone https://github.com/JordanGunn/gdal-mcp.git
cd gdal-mcp
uv sync
uv run gdal --transport stdio
See QUICKSTART.md for detailed setup instructions.
Use VS Code with the provided devcontainer for a pre-configured development environment:
# Open in VS Code and select "Reopen in Container"
# Everything is set up automatically!
See CONTRIBUTING.md and .devcontainer/README.md for details.
See QUICKSTART.md for detailed setup instructions.
raster_infoInspect raster metadata without reading pixel data.
Use cases: Understand projection, resolution, extent before processing
Input: uri (path to raster)
Output: Driver, CRS, bounds, transform, dimensions, data type, nodata value, overview levels
Example conversation:
User: "What's the CRS and resolution of elevation.tif?"
AI: *calls raster_info*
"The DEM is in EPSG:4326 (WGS84) with 0.000277° resolution (~30m at equator).
It covers bounds: [-122.5, 37.5, -122.0, 38.0]"
raster_convertFormat conversion with compression and multi-resolution overviews.
Use cases: Create Cloud-Optimized GeoTIFFs, reduce file size, build pyramids for fast rendering
Key options:
driver: GTiff, COG, PNG, JPEG (COG = Cloud-Optimized GeoTIFF)compression: deflate, lzw, zstd, jpeg (case-insensitive)tiled: 256×256 blocks for efficient partial readsoverviews: [2, 4, 8, 16] for multi-resolution displayExample conversation:
User: "Optimize this 5GB satellite image for web serving"
AI: "Converting to COG with DEFLATE compression and overviews..."
*calls raster_convert with driver=COG, compression=deflate, overviews=[2,4,8,16]*
"Done! Reduced to 1.2GB (76% savings). Ready for cloud storage with efficient range requests."
raster_reproject ⚡ Reflection-enabledReproject to new coordinate system with methodological justification.
🧠 Triggers reflection for:
Use cases: Transform to analysis-appropriate CRS, align multiple datasets, prepare for web mapping
Required parameters:
dst_crs: Target projection (e.g., "EPSG:32610" for UTM Zone 10N)resampling: Interpolation method
nearest — Categorical data (land cover, classified imagery)bilinear — Fast, good for continuous datacubic — Smoothest, best for DEMs and visualizationlanczos — Highest quality, slowerOptional parameters:
resolution: Target pixel size [x, y] in destination unitsbounds: Crop to area of interest [left, bottom, right, top]Example conversation:
User: "Reproject this land cover map to UTM for area calculations"
AI: *raster_info shows categorical data*
*reflection: Why UTM? → accurate area/distance in local zone*
*reflection: Why nearest? → preserves exact class values, no new categories*
"Reprojecting to EPSG:32610 with nearest-neighbor to preserve classification..."
*executes with justified methodology*
raster_statsCompute statistical summaries and histograms.
Use cases: Understand data distribution, find outliers, validate processing results
Output: min, max, mean, std, median, percentiles, histogram (optional)
Example conversation:
User: "Check the elevation range in this DEM"
AI: *calls raster_stats*
"Elevation ranges from 145m to 2,847m with mean 892m.
Distribution shows two peaks (bimodal) - likely valley and ridge areas."
vector_infoInspect vector dataset metadata (Shapefile, GeoJSON, GeoPackage, etc.).
Output: Driver, CRS, geometry types, feature count, field schema, bounds
Example conversation:
User: "What's in this shapefile?"
AI: *calls vector_info*
"It's a polygon layer with 1,247 parcels in EPSG:2227 (California State Plane).
Fields: parcel_id (string), area_sqft (float), zoning (string), assessed_value (int)"
store_justificationExplicitly cache epistemic justifications (used internally by reflection system).
Purpose: Allows AI to store methodological reasoning for future operations
When called: Automatically after reflection prompts, or manually for custom workflows
Cache structure: .preflight/justifications/{domain}/sha256:{hash}.json
Run the comprehensive test suite:
# All tests with pytest
uv run pytest test/ -v
# With coverage
uv run pytest test/ --cov=src --cov-report=term-missing
# Specific test file
uv run pytest test/test_raster_tools.py -v
Current Status: ✅ 72 tests passing (includes reflection system, prompts, and full integration suite)
Test fixtures create tiny synthetic datasets (10×10 rasters, 3-feature vectors) for fast validation.
See QUICKSTART.md for full instructions. Quick version:
~/Library/Application Support/Claude/claude_desktop_config.json on macOS):{
"mcpServers": {
"gdal-mcp": {
"command": "uvx",
"args": ["--from", "gdal", "gdal", "--transport", "stdio"],
"env": {
"GDAL_CACHEMAX": "512"
}
}
}
}
Python-Native Stack (ADR-0017):
Design Principles (see docs/design/):
Getting Started:
Development:
Key ADRs:
We welcome contributions! See CONTRIBUTING.md for:
MIT License - see LICENSE for details.
Reflection middleware:
raster_reproject toolProduction infrastructure:
New reflection triggers:
Workflow composition:
Vector analysis:
Raster analysis:
Semantic capabilities:
See docs/ROADMAP.md for detailed milestones and technical planning.
Status: v1.0.0 Production Release 🚀
The first geospatial MCP server that doesn't just execute operations—it reasons about them.
Core innovation: Epistemic governance through reflection middleware. AI agents must justify methodological choices (CRS, resampling, aggregation) before execution. Justifications are cached for workflow efficiency while maintaining scientific rigor.
Vision: Enable discovery of novel geospatial analysis workflows through tool composition with domain understanding, not just prescribed procedures.
Built with ❤️ for the geospatial AI community.
Please log in to share your review and rating for this MCP.
{
"mcpServers": {
"gdal-mcp": {
"command": "uvx",
"args": [
"--from",
"gdal-mcp",
"gdal",
"--transport",
"stdio"
],
"env": {}
}
}
}claude mcp add gdal-mcp uvx --from gdal-mcp gdal --transport stdioExplore related MCPs that share similar capabilities and solve comparable challenges
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.