Metadata-Version: 2.4
Name: mcp-geo
Version: 0.2.0
Summary: Geospatial MCP server — give AI agents geocoding, routing, spatial ops, and OSM querying via the Model Context Protocol
Author: Tabib Hasan
License: MIT
License-File: LICENSE
Keywords: geocoding,geospatial,gis,mcp,model-context-protocol,openstreetmap,routing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyproj>=3.5
Requires-Dist: shapely>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: files
Requires-Dist: geopandas>=0.14; extra == 'files'
Requires-Dist: pyogrio>=0.8; extra == 'files'
Provides-Extra: raster
Requires-Dist: rasterio>=1.3; extra == 'raster'
Requires-Dist: rasterstats>=0.19; extra == 'raster'
Description-Content-Type: text/markdown

# mcp-geo

A batteries-included geospatial server for the Model Context Protocol.  
It gives AI agents real access to geocoding, routing, OpenStreetMap querying,  
and spatial geometry operations — all returning clean GeoJSON.

[![PyPI version](https://img.shields.io/pypi/v/mcp-geo.svg)](https://pypi.org/project/mcp-geo/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/tabibhasann/geo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/tabibhasann/geo-mcp/actions/workflows/ci.yml)

## Quickstart

No configuration required — it runs out of the box with public OSM services.

```bash
pip install mcp-geo
```

Add it to your MCP client:

```json
{
  "mcpServers": {
    "geo": { "command": "uvx", "args": ["mcp-geo"] }
  }
}
```

That is it. Your AI agent now has 20+ geospatial tools available.

## Tools

**Local geometry (no network)**
`buffer` · `distance` · `area` · `length` · `centroid` · `simplify` · `convex_hull` · `bbox` · `spatial_predicate` · `transform_crs` · `validate_geojson`

**Geocoding & reverse geocoding (Nominatim)**
`geocode` · `reverse_geocode`

**OpenStreetMap querying (Overpass)**
`build_overpass_query` · `osm_features` · `overpass_query`

**Routing (OSRM)**
`route` · `route_matrix` · `nearest_road`

**File inspection (optional extras)**
`vector_info` · `vector_read` (`pip install mcp-geo[files]`)  
`raster_info` · `zonal_stats` · `sample_raster` (`pip install mcp-geo[raster]`)

All network tools respect rate limits and use a proper User-Agent header.

## Example: an agent answering a real spatial question

*"Find hospitals within 2 km of the Buriganga river in Dhaka"*

The agent composes four tools:
1. `geocode("Buriganga River, Dhaka")` → coordinates
2. `buffer(river, 2000)` → 2 km polygon
3. `osm_features(buffer, {"amenity": "hospital"})` → GeoJSON of hospitals
4. `distance` → sort by proximity

The agent handles the reasoning — mcp-geo handles the execution reliably.

## Configuration

Everything works without any setup. If you need to point at self-hosted
services (higher rate limits, air-gapped environments), set these environment
variables:

| Variable | Default |
|----------|---------|
| `GEO_MCP_NOMINATIM_URL` | `https://nominatim.openstreetmap.org` |
| `GEO_MCP_OSRM_URL` | `https://router.project-osrm.org` |
| `GEO_MCP_OVERPASS_URL` | `https://overpass-api.de/api/interpreter` |

Rate limiting is enforced client-side — **1 request per second** to Nominatim
by default. For production use, consider running your own Nominatim, OSRM,
and Overpass instances.

## Development

```bash
pip install -e ".[dev]"
ruff check src/ tests/
mypy src/
pytest --cov=geo_mcp tests/ -v
```

## License

MIT
