# SatMCP - Satellite image contex for intelligent systems

> Search and view recent or archived satellite imagery by place and date through a free REST API and MCP server.

## What is SatMCP?

SatMCP makes satellite imagery accessible to agents, developers, and people through simple place-and-date queries. Instead of dealing with complex geospatial coordinates and satellite data formats, ask for imagery of "Pretoria" or "Cape Town" and get usable image results.

## API Endpoint

Base URL: https://satmcp.com/api/v1

### Search for Satellite Imagery

```
GET /api/v1/search?place={place_name}&date={date_or_datetime}
```

Parameters:
- `place` (required): Place name to search for (e.g., "Pretoria", "Cape Town", "Paris")
- `date` (optional): Natural-language/string date or ISO 8601 date-time (e.g., "last week" or "2026-07-10T14:30:00Z"). Defaults to yesterday.

Response:
```json
{
  "place": "Pretoria",
  "date": "2024-01-15",
  "image_url": "https://satmcp.com/api/v1/images/eyJhIj...Q.5f4dcc3b5aa765d61d8327deb882cf99...",
  "scene_id": "S2A_MSIL2A_20240115T...",
  "satellite": "sentinel-2a",
  "attribution": "Copernicus Sentinel",
  "resolution": "10m",
  "captured_at_utc": "2024-01-15T08:32:00+00:00"
}
```

### Search for Multiple Images

```
GET /api/v1/search/list?place=Dubai&date=last%20week&max_results=10
```

Streams `result`, `done`, and `error` events over SSE by default. Add `stream=false`
to receive one buffered JSON object with `results` and `count`.

### Fetch an Image Directly

```
GET /api/v1/images/{image_id}
```

Returns the satellite image as binary `image/webp`. Clients should use the complete
`image_url` returned by search rather than extracting its opaque identifier.

Cloudflare caches `/api/v1/images/*`. Other API routes (including `/api/v1/search` and `/api/v1/search/list`), `/auth/*` (including `/auth/profile`), and `/mcp` are dynamic and not edge-cached.

Recommended Cloudflare Cache Rule expression:

```text
(http.request.method in {"GET" "HEAD"}) and (
  starts_with(http.request.uri.path, "/api/v1/images/")
  or (
    not starts_with(http.request.uri.path, "/api/")
    and not starts_with(http.request.uri.path, "/auth")
    and not starts_with(http.request.uri.path, "/mcp")
    and not starts_with(http.request.uri.path, "/profile")
  )
)
```

Recommended rule behavior:

- Use Cache-Control header if present, cache request with Cloudflare's default TTL for the response status if not
- Add a status-code override for `404` → `7 days` to absorb crawler traffic

### Health Check

```
GET /api/v1/health/live
```

## Data Sources

- **Geocoding**: OpenStreetMap Nominatim (place name to coordinates)
- **Imagery**: Copernicus Sentinel-2 and public Landsat imagery

## Use Cases

1. **Weather verification**: Check if it was cloudy in a location on a specific date
2. **Land use analysis**: View agricultural areas, urban development, forests
3. **Environmental monitoring**: Track changes in vegetation, water bodies
4. **Disaster response**: View affected areas after floods, fires, etc.
5. **Education**: Explore Earth from space for learning purposes
6. **Machine linking**: Use top-level `image_url` to link to a persistent binary image URL

## Integration

- **REST API**: Standard HTTP endpoints with JSON responses
- **MCP Server**: Remote Streamable HTTP endpoint at https://satmcp.com/mcp/
- **Authentication**: Create a personal token at https://satmcp.com/auth/profile and send it on every MCP request as `Authorization: Bearer YOUR_SATMCP_TOKEN`. SatMCP does not currently expose an interactive MCP OAuth flow.
- **MCP tools**: `search_satellite_imagery` returns compact metadata and direct image URLs. When the user asks to see a result inline, pass its exact `image_url` to `get_satellite_image`, which returns native MCP image content. The MCP client decides whether and how to render it.
- **OpenAPI**: Public API documentation at /api/v1/docs (search and images only)

## Example Queries

- "Show me satellite imagery of Pretoria"
- "What did Cape Town look like from space on January 15, 2024?"
- "Get a satellite image of the Amazon rainforest"
- "Satellite view of Tokyo"

## Links

- Website: https://satmcp.com
- API Docs: https://satmcp.com/api/v1/docs
- OpenAPI Spec: https://satmcp.com/api/v1/openapi.json
- MCP Server: https://satmcp.com/mcp/
- Integrations: https://satmcp.com/integrations
- Contact: hello@satmcp.com