clip_raster_with_shapefile

Extract raster data within polygon boundaries from a shapefile. Converts coordinate systems automatically and saves the clipped raster to a specified location.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`raster_path_or_url`	Yes
`shapefile_path`	Yes
`destination`	Yes

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")
```

GIS MCP Server