JordanGunn/gdal-mcp

MCP server exposing GDAL/Rasterio operations to AI agents, with a reflection
middleware that requires structured justification before executing operations
whose methodology matters (CRS choice, resampling method, query extent).
Install
Via uvx (recommended)
Via Docker
Local development
Configure your MCP client
Claude Desktop
Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/,
Windows: %APPDATA%\Claude\, Linux: ~/.config/Claude/):
Restart Claude Desktop. The MCP server indicator should appear, and the
raster_* and vector_* tools become available.
Workspace scoping
GDAL_MCP_WORKSPACES is a colon-separated list of directories the server
is allowed to touch. If unset, all paths are allowed and a warning is logged.
Optional tool-surface flags: RASTER=true, VECTOR=true. See
docs/ENVIRONMENT_VARIABLES.md for the full set.
Tools
- **Raster:** raster_info, raster_convert, raster_reproject, raster_stats, raster_query
- **Vector:** vector_info, vector_convert, vector_reproject, vector_clip, vector_buffer, vector_simplify, vector_query
- **Resources:** catalog (workspace://...), metadata (metadata://...), reference (reference://...), query results (query://result/{id})
- **Prompts:** justify_crs_selection, justify_resampling_method, justify_query_extent (and more under src/prompts/)
See TOOLS.md for parameters, return shapes, and worked examples.
The reflection middleware
Tools whose methodology matters refuse to execute until the calling agent
produces a structured justification. The flow is:
1. Agent calls e.g. raster_reproject(dst_crs="EPSG:3857", resampling="cubic", ...).
2. Middleware checks .preflight/justifications/{domain}/ for a matching hash.
3. On miss, the call raises ToolError with a hint pointing at the
relevant prompt (e.g. justify_crs_selection).
4. Agent calls the prompt, fills out the Justification schema (intent,
alternatives considered, choice, tradeoffs, confidence), and re-invokes
the tool with a __reflection payload.
5. The justification is cached domain-keyed, so a CRS rationale for
EPSG:3857 satisfies both raster_reproject and vector_reproject
on subsequent calls.
See docs/REFLECTION.md for the schema and cache layout,
and docs/PHILOSOPHY.md for why this exists.
Documentation
- TOOLS.md — tool reference
- docs/ENVIRONMENT_VARIABLES.md — runtime config
- docs/REFLECTION.md — reflection middleware internals