Overview

The STAC MCP Server provides a focused implementation for catalog and item search over geospatial datasets using STAC-style APIs. It exposes a compact HTTP interface that lets clients discover catalogs, list collections, and perform spatial/temporal searches for STAC Items — useful for quickly locating imagery, vector products, or derived datasets based on bounding boxes, datetimes, collections, and metadata queries.

This server is intended for developers building discovery layers, data portals, or automated pipelines that need fast dataset lookup without the overhead of a full catalog management platform. It can be deployed locally for development or run behind a reverse proxy in production, and it is configurable to point at a static STAC catalog directory or a backing index for faster item search.

Features

STAC-style Catalog endpoint for top-level discovery
Item search (POST /search) supporting bbox, datetime, collections, limit and property queries
Lightweight, container-friendly server suitable for local development and CI
Configurable data source: static catalog directory or indexed store
JSON API compatible with STAC Item and FeatureCollection responses
Basic filtering and pagination support
Example client snippets (curl, Python) for quick integration

Installation / Configuration

Prerequisites: Docker (recommended) or Python 3.8+ / Node.js (if building locally from source — see repo).

Clone the repository:

git clone https://github.com/Wayfinder-Foundry/stac-mcp.git
cd stac-mcp

Run with Docker:

# build and run
docker build -t stac-mcp .
docker run -p 8080:8080 \
  -e DATA_DIR=/data/catalog \
  -v /path/to/your/stac/catalog:/data/catalog:ro \
  stac-mcp

Example docker-compose.yml:

version: "3.7"
services:
  stac-mcp:
    image: stac-mcp:latest
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./catalog:/data/catalog:ro
    environment:
      - PORT=8080
      - DATA_DIR=/data/catalog
      - LOG_LEVEL=info

Simple configuration file (config.yml):

server:
  host: 0.0.0.0
  port: 8080

storage:
  type: filesystem
  path: /data/catalog

search:
  default_limit: 10
  max_limit: 100

Environment variables commonly used:

DATA_DIR — path to STAC catalog directory
PORT — HTTP port to listen on
LOG_LEVEL — debug/info/warn/error

Available Resources

The server exposes a small set of HTTP endpoints for discovery and search. Adjust paths if your deployment prefixes the API.

Method	Path	Description
GET	/catalog	Top-level STAC Catalog (JSON)
POST	/search	Item search endpoint accepting STAC-like search payloads
GET	/search	Optional GET-based search using query parameters (bbox, datetime, collections)
GET	/collections	Lists collections available in the catalog

Notes:

Responses follow STAC conventions: Catalogs, Collections, Items, and FeatureCollection for search results.
The server can be configured to return an OpenAPI/Swagger UI if enabled in config.

Use Cases

Web map layer selector

Use GET /catalog to populate a list of available collections.
When a user draws a bounding box and date range, POST /search to get matching Items and select assets to display.

Example curl:

curl -s -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "bbox": [-122.6, 37.6, -122.2, 37.9],
    "datetime": "2022-01-01/2022-12-31",
    "collections": ["sentinel-2"],
    "limit": 5
  }' | jq .

Ingest pipeline filter

A machine learning pipeline can query /search for items within a production area and a date window, then download assets listed in Item.assets for processing.

Python example:

import requests
payload = {
    "bbox": [-79.5, 43.6, -79.2, 43.8],
    "datetime": "2023-01-01/2023-03-31",
    "limit": 20
}
r = requests.post("http://localhost:8080/search", json=payload)
items = r.json().get("features", [])
for item in items:
    print(item["id"], item["assets"].keys())

Automated QA and monitoring
- Regularly poll /collections or /search for new Items matching ingestion rules to trigger alerting or downstream jobs.

Troubleshooting & Resources

GitHub repository (source, issues, examples): https://github.com/Wayfinder-Foundry/stac-mcp
If search returns no results:
- Verify DATA_DIR points to a valid STAC catalog structure.
- Check server logs (set LOG_LEVEL=debug) for parsing/indexing errors.
If you need higher performance for large catalogs, consider adding an index layer (Elasticsearch, SQLite) and configuring the server to use it (see config storage.type).

This server is intended as a minimal, deployable component for STAC-based discovery workflows — fast to run locally and simple to integrate into larger geospatial systems.

STAC MCP Server: Catalog and Item Search