Metadata-Version: 2.4
Name: mcp-geo
Version: 0.1.4
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

# geo-mcp 🗺️

> **The batteries-included geospatial MCP server**. Give any AI agent real geospatial superpowers — geocoding, routing, spatial geometry operations, OpenStreetMap querying, and raster/vector inspection — all returning clean GeoJSON.

[![PyPI version](https://img.shields.io/pypi/v/geo-mcp.svg)](https://pypi.org/project/geo-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.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

```bash
# Run directly (no install needed)
uvx geo-mcp

# Or install globally
pip install geo-mcp
geo-mcp
```

Add to your MCP client (Claude Desktop, Cursor, etc.):

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

---

## What it does

**geo-mcp** exposes 20+ geospatial tools to AI agents through the Model Context Protocol:

| Category | Tools |
|----------|-------|
| **Geometry** | buffer, distance, area, length, centroid, simplify, convex_hull, bbox, spatial_predicate, transform_crs, validate_geojson |
| **Geocoding** | geocode (forward), reverse_geocode (Nominatim/OSM) |
| **OSM/Overpass** | build_overpass_query, osm_features, overpass_query |
| **Routing** | route, route_matrix, nearest_road (OSRM) |
| **Vector** | vector_info, vector_read (optional: `pip install mcp-geo[files]`) |
| **Raster** | raster_info, zonal_stats, sample_raster (optional: `pip install geo-mcp[raster]`) |

All tools return GeoJSON. All network tools use proper User-Agent headers and client-side rate limiting.

---

## Example: Agent answers a spatial question

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

1. `geocode` → coordinates of "Buriganga River, Dhaka"
2. `buffer` → 2 km buffer polygon around the river
3. `osm_features` → amenities tagged `hospital` within the buffer
4. `distance` → sort hospitals by distance to downtown Dhaka

The agent composes these tools — the server handles the **execution, validation, and GeoJSON return** reliably.

---

## Configuration

Set via environment variables (or `.env` file):

| Variable | Default | Description |
|----------|---------|-------------|
| `GEO_MCP_NOMINATIM_URL` | `https://nominatim.openstreetmap.org` | Geocoding provider |
| `GEO_MCP_OSRM_URL` | `https://router.project-osrm.org` | Routing provider |
| `GEO_MCP_OVERPASS_URL` | `https://overpass-api.de/api/interpreter` | Overpass API |
| `GEO_MCP_USER_AGENT` | `geo-mcp/0.1.0` | HTTP User-Agent |
| `GEO_MCP_NOMINATIM_RATE_LIMIT` | `1.0` | Nominatim requests/sec |

For production use, consider self-hosting your own Nominatim/OSRM/Overpass instances.

---

## Development

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

## License

MIT — see [LICENSE](LICENSE).
