Skip to main content

GDAL MCP

Democratizing geospatial analysis through conversational AI

GDAL MCP is a production-ready MCP server that exposes powerful geospatial operations through natural language interaction. Built with empathy for domain experts who need GDAL's capabilities without the CLI complexity.

🎉 Milestone (2025-09-30): First successful live tool invocation - GDAL operations are now conversational! 🚀 Update (2025-10-10): Phase 2A resource suite shipped (metadata/catalog/reference) – unlocking autonomous geospatial reasoning workflows.

CI License: MIT Python 3.11+ FastMCP 2.0 PyPI Downloads

🌟 Vision

Bridging the gap between geospatial domain experts and powerful tools.

Instead of requiring analysts to master:

  • Command-line interfaces
  • Python programming
  • System configuration
  • GDAL syntax

Users can now ask in natural language:

  • "Show me the metadata for this raster"
  • "Convert this to Cloud-Optimized GeoTIFF with compression"
  • "Reproject this DEM to Web Mercator using cubic resampling"

The AI agent uses GDAL MCP under the hood - properly, safely, with production-quality code.

🚀 Features

  • ✅ Production-Ready: First live tool invocation successful (2025-09-30)
  • 🧭 Resource Discovery (0.2.0): catalog://workspace/{all|raster|vector}/{subpath} resources expose the active workspace so agents can plan without manual file listings.
  • 🔍 Metadata Intelligence (0.2.0): metadata://{file}/format surfaces driver/format details alongside existing raster/vector metadata.
  • 📚 Reference Library (0.2.0): CRS, resampling, compression, and glossary resources provide curated knowledge for agents (reference://crs/common/{coverage}, etc.).
  • Python-Native Stack: Rasterio, PyProj, pyogrio, Shapely (no GDAL CLI dependency)
  • 5 Core Tools: raster_info, raster_convert, raster_reproject, raster_stats, vector_info
  • Type-Safe: Pydantic models with auto-generated JSON schemas
  • Workspace Security: PathValidationMiddleware for secure file access (ADR-0022)
  • Context Support: Real-time LLM feedback during long operations (ADR-0020)
  • FastMCP 2.0: Native configuration, middleware, Context API
  • CI/CD Pipeline: GitHub Actions with quality gates, test matrix, PyPI publishing
  • Comprehensive Tests: 23/23 tests passing across Python 3.11-3.12
  • ADR-Documented: 25 architecture decisions guiding development

📦 Installation

# Run directly without installation
uvx --from gdal-mcp gdal --transport stdio

Method 2: Docker

# Build and run
docker build -t gdal-mcp .
docker run -i gdal --transport stdio

Method 3: Local Development

# 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.

🔧 Available Tools

Raster Tools

raster_info

Inspect raster metadata using Rasterio.

Input: uri (str), optional band (int)

Output: RasterInfo with:

  • Driver, CRS, bounds, transform
  • Width, height, band count, dtype
  • NoData value, overview levels, tags

Example: Get metadata for a GeoTIFF

{
  "uri": "/data/example.tif",
  "band": 1
}

raster_convert

Convert raster formats with compression, tiling, and overviews.

Input: uri (str), output (str), optional options (ConversionOptions)

Options:

  • driver: Output format (GTiff, COG, PNG, JPEG, etc.)
  • compression: lzw, deflate, zstd, jpeg, packbits, none
  • tiled: Create tiled output (default: True)
  • blockxsize/blockysize: Tile dimensions (default: 256×256)
  • overviews: List of overview levels (e.g., [2, 4, 8, 16])
  • overview_resampling: nearest, bilinear, cubic, average, mode

Example: Convert to Cloud-Optimized GeoTIFF with compression

{
  "uri": "/data/input.tif",
  "output": "/data/output_cog.tif",
  "options": {
    "driver": "COG",
    "compression": "deflate",
    "overviews": [2, 4, 8, 16]
  }
}

raster_reproject

Reproject raster to new CRS with explicit resampling method (ADR-0011 requirement).

Input: uri (str), output (str), params (ReprojectionParams)

Required Params:

  • dst_crs: Target CRS (e.g., "EPSG:3857", "EPSG:4326")
  • resampling: Resampling method (nearest, bilinear, cubic, lanczos, etc.)

Optional Params:

  • src_crs: Override source CRS if missing/incorrect
  • resolution: Target pixel size as (x, y) tuple
  • width/height: Explicit output dimensions
  • bounds: Crop to extent (left, bottom, right, top)

Example: Reproject DEM to Web Mercator with cubic resampling

{
  "uri": "/data/dem.tif",
  "output": "/data/dem_webmercator.tif",
  "params": {
    "dst_crs": "EPSG:3857",
    "resampling": "cubic"
  }
}

raster_stats

Compute comprehensive statistics for raster bands.

Input: uri (str), optional params (RasterStatsParams)

Optional Params:

  • bands: List of band indices (None = all bands)
  • include_histogram: Generate histogram (default: False)
  • histogram_bins: Number of bins (default: 256)
  • percentiles: Compute specific percentiles (e.g., [25, 50, 75])
  • sample_size: Sample random pixels for large rasters

Output: RasterStatsResult with per-band statistics:

  • min, max, mean, std, median
  • percentile_25, percentile_75
  • valid_count, nodata_count
  • Optional histogram bins

Example: Compute statistics with histogram for band 1

{
  "uri": "/data/landsat.tif",
  "params": {
    "bands": [1],
    "include_histogram": true,
    "percentiles": [10, 25, 50, 75, 90]
  }
}

Vector Tools

vector_info

Inspect vector dataset metadata using pyogrio (with fiona fallback).

Input: uri (str)

Output: VectorInfo with:

  • Driver (e.g., "ESRI Shapefile", "GeoJSON", "GPKG")
  • CRS, layer count, geometry types
  • Feature count, field schema
  • Spatial bounds

Example: Get metadata for Shapefile

{
  "uri": "/data/parcels.shp"
}

🧪 Testing

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: ✅ 58 tests passing (catalog, metadata, reference, band metadata suites)

Test fixtures create tiny synthetic datasets (10×10 rasters, 3-feature vectors) for fast validation.

🔌 Connecting to Claude Desktop

See QUICKSTART.md for full instructions. Quick version:

  1. Add to your Claude Desktop config (~/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"
      }
    }
  }
}
  1. Restart Claude Desktop
  2. Test with: "Use raster_info to inspect /path/to/raster.tif"

🏗️ Architecture

Python-Native Stack (ADR-0017):

  • Rasterio - Raster I/O and manipulation
  • PyProj - CRS operations and transformations
  • pyogrio - High-performance vector I/O (fiona fallback)
  • Shapely - Geometry operations
  • NumPy - Array operations and statistics
  • Pydantic - Type-safe models with JSON schema

Design Principles (see docs/design/):

  • ADR-0007: Structured outputs with Pydantic
  • ADR-0011: Explicit resampling methods
  • ADR-0012: Large outputs via ResourceRef
  • ADR-0013: Per-request config isolation
  • ADR-0017: Python-native over CLI shelling

📚 Documentation

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

  • Development setup
  • Code style guide (Ruff + mypy)
  • Testing requirements (pytest + fixtures)
  • ADR process

📝 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

🔮 Roadmap

MVP Complete ✅:

  • ✅ Raster tools (info, convert, reproject, stats)
  • ✅ Vector info tool
  • ✅ Comprehensive tests (23/23)
  • ✅ Docker deployment
  • ✅ MCP client integration

0.2.0 Achievements:

  • Phase 2A resources (ADR-0023) delivered: catalog discovery, metadata format inspection, knowledge/reference APIs.
  • Shared reference utilities enable smarter agent planning (resampling heuristics, CRS guidance, compression catalog, glossary).
  • Styleguide and ADR additions (0023–0025) guide future contributions.

Next Steps:

  • Phase 2C context/history resources (session state, provenance).
  • Phase 2D domain references expansion (terrain analysis guides, advanced format primers).
  • Expanded spatial analysis tools and workflows powered by new reference knowledge.

Status: MVP Ready for Public Release 🚀

Built with ❤️ for the geospatial AI community.

Metadata

Release files for gdal-mcp 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gdal-mcp 0.2.1
File Size Uploaded Provenance Actions
gdal_mcp-0.2.1.tar.gz 245.1 kB With provenance Details for gdal_mcp-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gdal-mcp 0.2.1
File Interpreter ABI Platform Actions
gdal_mcp-0.2.1-py3-none-any.whl Python 3 none any Details for gdal_mcp-0.2.1-py3-none-any.whl

Total release size: 315.4 kB

Release files / gdal_mcp-0.2.1.tar.gz

Download URL gdal_mcp-0.2.1.tar.gz
Size 245.1 kB
Tags Source
SHA-256 checksum
How to use checksums
3cfe5f5d053baedd139238b24d68efd252d93668244a2f1fe1dfc22018f339eb
BLAKE2b-256 checksum
How to use checksums
08a873443b900e28dc04def9b61f25a4ce2be77fb4adaa727d51bf83785c433f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2025.

Transparency log

Release files / gdal_mcp-0.2.1-py3-none-any.whl

Download URL gdal_mcp-0.2.1-py3-none-any.whl
Size 70.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
18cea1e0afe04819c1f9b2b555b8c17835744bab807c0661501f7b1af2dcce18
BLAKE2b-256 checksum
How to use checksums
45fd21d5f85070a68d118fdf52ed7334861eccb13e33818c8826856dc653d36d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2025.

Transparency log

Security for gdal-mcp 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gdal_mcp-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page