Skip to content
Back to search

gdal-mcp

Model Context Protocol server that packages GDAL-style geospatial workflows through Python-native libraries (Rasterio, GeoPandas, PyProj, etc.) to give AI agents catalog discovery, metadata intelligence, and raster/vector processing with built-in reasoning guidance and reference resources.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jordangunn--gdal-mcp/badge.svg)](/listings/jordangunn--gdal-mcp)

HTML

<a href="/listings/jordangunn--gdal-mcp"><img src="/api/listings/jordangunn--gdal-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Via uvx (recommended)

uvx --from gdal-mcp gdal --transport stdio

Via Docker

docker build -t gdal-mcp .
docker run -i gdal-mcp gdal --transport stdio

Local development

git clone https://github.com/Wayfinder-Foundry/gdal-mcp.git
cd gdal-mcp
uv sync
uv run gdal --transport stdio

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 121 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # gdal-mcp
  2. MCP server exposing GDAL/Rasterio operations to AI agents, with a reflection
  3. middleware that requires structured justification before executing operations
  4. whose methodology matters (CRS choice, resampling method, query extent).
  5. [![CI](https://github.com/Wayfinder-Foundry/gdal-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Wayfinder-Foundry/gdal-mcp/actions/workflows/ci.yml)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  7. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  8. [![FastMCP 2.0](https://img.shields.io/badge/FastMCP-2.0-blue.svg)](https://github.com/jlowin/fastmcp)
  9. [![PyPI Downloads](https://static.pepy.tech/personalized-badge/gdal-mcp?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/gdal-mcp)
  10. ## Install
  11. ### Via uvx (recommended)
  12. ```bash
  13. uvx --from gdal-mcp gdal --transport stdio
  14. ```
  15. ### Via Docker
  16. ```bash
  17. docker build -t gdal-mcp .
  18. docker run -i gdal-mcp gdal --transport stdio
  19. ```
  20. ### Local development
  21. ```bash
  22. git clone https://github.com/Wayfinder-Foundry/gdal-mcp.git
  23. cd gdal-mcp
  24. uv sync
  25. uv run gdal --transport stdio
  26. ```
  27. ## Configure your MCP client
  28. ### Claude Desktop
  29. Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`,
  30. Windows: `%APPDATA%\Claude\`, Linux: `~/.config/Claude/`):
  31. ```json
  32. {
  33. "mcpServers": {
  34. "gdal-mcp": {
  35. "command": "uvx",
  36. "args": ["--from", "gdal-mcp", "gdal", "--transport", "stdio"],
  37. "env": {
  38. "GDAL_MCP_WORKSPACES": "/path/to/your/geospatial/data"
  39. }
  40. }
  41. }
  42. }
  43. ```
  44. Restart Claude Desktop. The MCP server indicator should appear, and the
  45. `raster_*` and `vector_*` tools become available.
  46. ### Workspace scoping
  47. `GDAL_MCP_WORKSPACES` is a colon-separated list of directories the server
  48. is allowed to touch. If unset, all paths are allowed and a warning is logged.
  49. Optional tool-surface flags: `RASTER=true`, `VECTOR=true`. See
  50. [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) for the full set.
  51. ## Tools
  52. - **Raster:** `raster_info`, `raster_convert`, `raster_reproject`, `raster_stats`, `raster_query`
  53. - **Vector:** `vector_info`, `vector_convert`, `vector_reproject`, `vector_clip`, `vector_buffer`, `vector_simplify`, `vector_query`
  54. - **Resources:** catalog (`workspace://...`), metadata (`metadata://...`), reference (`reference://...`), query results (`query://result/{id}`)
  55. - **Prompts:** `justify_crs_selection`, `justify_resampling_method`, `justify_query_extent` (and more under `src/prompts/`)
  56. See [TOOLS.md](TOOLS.md) for parameters, return shapes, and worked examples.
  57. ## The reflection middleware
  58. Tools whose methodology matters refuse to execute until the calling agent
  59. produces a structured justification. The flow is:
  60. 1. Agent calls e.g. `raster_reproject(dst_crs="EPSG:3857", resampling="cubic", ...)`.
  61. 2. Middleware checks `.preflight/justifications/{domain}/` for a matching hash.
  62. 3. On miss, the call raises `ToolError` with a hint pointing at the
  63. relevant prompt (e.g. `justify_crs_selection`).
  64. 4. Agent calls the prompt, fills out the `Justification` schema (intent,
  65. alternatives considered, choice, tradeoffs, confidence), and re-invokes
  66. the tool with a `__reflection` payload.
  67. 5. The justification is cached domain-keyed, so a CRS rationale for
  68. EPSG:3857 satisfies both `raster_reproject` and `vector_reproject`
  69. on subsequent calls.
  70. See [docs/REFLECTION.md](docs/REFLECTION.md) for the schema and cache layout,
  71. and [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) for why this exists.
  72. ## Documentation
  73. - [TOOLS.md](TOOLS.md) — tool reference
  74. - [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) — runtime config
  75. - [docs/REFLECTION.md](docs/REFLECTION.md) — reflection middleware internals
  76. - [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) — design philosophy and direction
  77. - [docs/ROADMAP.md](docs/ROADMAP.md) — release history and direction
  78. - [CHANGELOG.md](CHANGELOG.md) — versioned changelog
  79. - [CONTRIBUTING.md](CONTRIBUTING.md) — contribution guide
  80. ## Troubleshooting
  81. **`Access denied: path outside allowed workspaces`** — set `GDAL_MCP_WORKSPACES`
  82. to include the directory in question (see "Workspace scoping").
  83. **MCP client doesn't see the server** — verify `uvx --from gdal-mcp gdal --help`
  84. runs on its own, then restart the client after editing its config file.
  85. ## License
  86. MIT — see [LICENSE](LICENSE).
  87. Built on [FastMCP](https://github.com/jlowin/fastmcp),
  88. [Rasterio](https://github.com/rasterio/rasterio), [pyogrio](https://github.com/geopandas/pyogrio),
  89. and [Shapely](https://github.com/shapely/shapely).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.