GIS MCP Server

Instructions

Implementation Reference

• src/gis_mcp/rasterio_functions.py:363-446 (handler)

  The core handler function decorated with @gis_mcp.tool(). It opens the raster (local or URL), reads shapefile geometries with fiona, reprojects geometries to raster CRS if needed, applies rasterio.mask to clip, and writes the output GeoTIFF.

  @gis_mcp.tool()
  def clip_raster_with_shapefile(
      raster_path_or_url: str,
      shapefile_path: str,
      destination: str
  ) -> Dict[str, Any]:
      """
      Clip a raster dataset using polygons from a shapefile and write the result.
      Converts the shapefile's CRS to match the raster's CRS if they are different.
      
      Parameters:
      - raster_path_or_url: local path or HTTPS URL of the source raster.
      - shapefile_path:     local filesystem path to a .shp file containing polygons.
      - destination:        local path where the masked raster will be written.
      """
      try:
          import numpy as np
          import rasterio
          import rasterio.mask
          from rasterio.warp import transform_geom
          import pyproj
          import fiona
  
          # Clean paths
          raster_clean = raster_path_or_url.replace("`", "")
          shp_clean = shapefile_path.replace("`", "")
          dst_clean = destination.replace("`", "")
  
          # Verify shapefile exists
          shp_path = os.path.expanduser(shp_clean)
          if not os.path.isfile(shp_path):
              raise FileNotFoundError(f"Shapefile not found at '{shp_path}'.")
  
          # Open the raster
          if raster_clean.lower().startswith("https://"):
              src = rasterio.open(raster_clean)
          else:
              src_path = os.path.expanduser(raster_clean)
              if not os.path.isfile(src_path):
                  raise FileNotFoundError(f"Raster not found at '{src_path}'.")
              src = rasterio.open(src_path)
  
          raster_crs = src.crs  # Get raster CRS
  
          # Read geometries from shapefile and check CRS
          with fiona.open(shp_path, "r") as shp:
              shapefile_crs = pyproj.CRS(shp.crs)  # Get shapefile CRS
              shapes: List[Dict[str, Any]] = [feat["geometry"] for feat in shp]
  
              # Convert geometries to raster CRS if necessary
              if shapefile_crs != raster_crs:
                  shapes = [transform_geom(str(shapefile_crs), str(raster_crs), shape) for shape in shapes]
  
          # Apply mask: crop to shapes and set outside pixels to zero
          out_image, out_transform = rasterio.mask.mask(src, shapes, crop=True)
          out_meta = src.meta.copy()
          src.close()
  
          # Update metadata for the masked output
          out_meta.update({
              "driver": "GTiff",
              "height": out_image.shape[1],
              "width": out_image.shape[2],
              "transform": out_transform
          })
  
          # Resolve destination path relative to storage
          dst_path = resolve_path(dst_clean, relative_to_storage=True)
          dst_path.parent.mkdir(parents=True, exist_ok=True)
  
          # Write the masked raster
          with rasterio.open(str(dst_path), "w", **out_meta) as dst:
              dst.write(out_image)
  
          return {
              "status": "success",
              "destination": str(dst_path),
              "message": f"Raster masked and saved to '{dst_path}'."
          }
  
      except Exception as e:
          print(f"Error: {e}")
          raise ValueError(f"Failed to mask raster: {e}")

• src/gis_mcp/main.py:66-72 (registration)

  Imports rasterio_functions.py (and others), executing the module code and triggering @gis_mcp.tool() decorators to register the clip_raster_with_shapefile tool with the FastMCP server.

  from . import (
      geopandas_functions,
      shapely_functions,
      rasterio_functions,
      pyproj_functions,
      pysal_functions,
  )

• src/gis_mcp/rasterio_functions.py:11-35 (helper)

  GIS resource endpoint that lists all available rasterio tools, including "clip_raster_with_shapefile", allowing clients to discover the tool.

  @gis_mcp.resource("gis://operation/rasterio")
  def get_rasterio_operations() -> Dict[str, List[str]]:
      """List available rasterio operations."""
      return {
          "operations": [
              "metadata_raster",
              "get_raster_crs",
              "clip_raster_with_shapefile",
              "resample_raster",
              "reproject_raster",
              "weighted_band_sum",
              "concat_bands",
              "raster_algebra",
              "compute_ndvi",
              "raster_histogram",
              "tile_raster",
              "raster_band_statistics",
              "extract_band",
              "zonal_statistics",
              "reclassify_raster",
              "focal_statistics",
              "hillshade",
              "write_raster"
          ]
      }

• src/gis_mcp/mcp.py:5-6 (registration)

  Defines the FastMCP server instance 'gis_mcp' to which all tools are registered via decorators.

  gis_mcp = FastMCP("GIS MCP")