🌍 bbox-mcp-server

The geospatial toolkit for AI agents. 6 tools, zero config — give any LLM the ability to parse, convert, query, and aggregate spatial data out of the box.

Every response includes a verification link to vibhorsingh.com/boundingbox so you can visually confirm results on an interactive map.

---

Why This Exists

The problem	How bbox-mcp solves it
"I have WKT but the API needs a GeoJSON bbox in EPSG:3857."	Parses 6 input formats, projects to 3,900+ EPSG codes, outputs in 9 formats — in one call.
"I keep getting the wrong OSM tags for Overpass queries."	list_osm_tags returns curated tag combos. No more hallucinated amenity=grocery.
"How many hospitals are in this district?"	aggregate_overpass_h3 queries Overpass and bins results into H3 hexagons server-side.
"Is this bounding box actually correct?"	Every response includes a clickable map link for visual verification.

---

Tools at a Glance

Tool	What it does	Key params
get_bounds	Convert and project a bbox across formats and coordinate systems	bbox, epsg, format, coord_order, zoom
get_h3_indices	Generate H3 hex cell indices covering a bbox	bbox, resolution, compact
generate_share_url	Create a shareable map link for a bbox	bbox
search_overpass	Query OpenStreetMap via Overpass QL	bbox, query, limit
list_osm_tags	Look up correct OSM tags for a category	category
aggregate_overpass_h3	Run an Overpass query and bin results into H3 hexagons	bbox, query, resolution

All tools accept location (natural language, requires Mapbox token) or bbox (coordinates, WKT, GeoJSON, etc).

---

Quick Start

Add to your MCP client config:

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bbox": {
      "command": "npx",
      "args": ["-y", "bbox-mcp-server"]
    }
  }
}

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "bbox": {
      "command": "npx",
      "args": ["-y", "bbox-mcp-server"]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bbox": {
      "command": "npx",
      "args": ["-y", "bbox-mcp-server"]
    }
  }
}

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "bbox": {
      "command": "npx",
      "args": ["-y", "bbox-mcp-server"]
    }
  }
}

Try: "Get the bounding box for Central Park in WKT format"

Optional Configuration

{
  "mcpServers": {
    "bbox": {
      "command": "npx",
      "args": ["-y", "bbox-mcp-server"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "pk.your-token-here",
        "OVERPASS_API_URL": "https://your.custom.overpass.instance/api/interpreter"
      }
    }
  }
}

Variable	Default	Description
MAPBOX_ACCESS_TOKEN	—	Enables natural language location search (e.g. "San Francisco")
OVERPASS_API_URL	auto	Custom Overpass endpoint. By default, rotates between overpass-api.de and kumi.systems.
MAX_H3_CELLS	50000	Safety cap for H3 grid generation

Or install globally: npm install -g bbox-mcp-server

---

Tool Reference

get_bounds

Convert and project a bounding box across 6 input formats, 9 output formats, and 3,900+ coordinate systems. Returns the center point and tile coordinates for the centroid.

Param	Type	Default	Description
bbox	string	—	Input geometry (coordinates, WKT, GeoJSON, ogrinfo extent)
epsg	string	"4326"	Target projection. Unknown codes auto-fetched from epsg.io.
format	string	"csv"	Output: csv, wkt, geojson-bbox, geojson-polygon, leaflet, overpass, ogc-bbox, kml, stac-bbox
coord_order	string	"lng,lat"	Swap to "lat,lng" for APIs that expect latitude first
zoom	number	15	Zoom level for tile coordinate calculation
precision	number	6	Decimal places in formatted output

💡 Prompt: "Get the bounding box for Central Park in WKT format projected to EPSG:32618"

---

get_h3_indices

Generate Uber H3 hexagonal cell indices covering a bounding box.

Param	Type	Default	Description
bbox	string	—	Input geometry
resolution	number	—	H3 resolution (0–15)
compact	boolean	false	Merge cells into coarser parents where possible
return_geometry	boolean	false	Include GeoJSON hex boundaries

💡 Prompt: "Give me H3 cells at resolution 7 for downtown Chicago, include the hex geometries"

---

search_overpass

Execute an Overpass QL query within a bounding box. Returns structured results with names, coordinates, and tags.

Param	Type	Default	Description
bbox	string	—	Input geometry
query	string	—	Overpass QL (e.g. nwr["amenity"="cafe"]). The server wraps it in a bbox filter automatically.
limit	number	100	Max elements returned

💡 Prompt: "Search for nwr["amenity"="bench"] in Central Park, limit 50"

---

list_osm_tags

Look up the correct OpenStreetMap tags for a category before writing an Overpass query.

Param	Type	Description
category	string	Broad category (e.g. "food", "health", "transport")

💡 Prompt: "What are the correct OSM tags for supermarkets?"

---

aggregate_overpass_h3

Run an Overpass query and bin results into H3 hexagons for spatial density analysis. Returns counts per cell and GeoJSON hex boundaries.

Param	Type	Default	Description
bbox	string	—	Input geometry
query	string	—	Overpass QL core query
resolution	number	8	H3 resolution for binning

💡 Prompt: "Aggregate all hospitals in Seattle into H3 bins at resolution 7"

---

generate_share_url

Generate a shareable link to visualize a bounding box on the interactive map at vibhorsingh.com/boundingbox.

Param	Type	Description
bbox	string	Input geometry

💡 Prompt: "Generate a share link for bbox 40.7128,-74.0060,40.7580,-73.9855"

---

Supported Input Formats

All tools auto-detect the input format. No need to specify which one you're using.

Format	Example
Raw coordinates	40.7128,-74.0060,40.7580,-73.9855
WKT	POLYGON((-74.006 40.712, -73.985 40.712, ...))
GeoJSON	{"type":"Feature","geometry":{...}}
GeoJSON bbox	{"bbox":[-74.006,40.712,-73.985,40.758]}
ogrinfo extent	Extent: (-74.006, 40.712) - (-73.985, 40.758)
Space-separated	40.7128 -74.0060 40.7580 -73.9855

---

🤖 For AI Agent Developers

Response structure

Every tool returns two content blocks:

1. Human-readable text — formatted output with the map verification link
2. Structured JSON — all computed data, machine-parseable

Example get_bounds JSON response:

{
  "original_wgs84": { "lat1": 40.7128, "lng1": -74.006, "lat2": 40.758, "lng2": -73.9855 },
  "projected": { "xmin": -8238310.23, "ymin": 4970241.32, "xmax": -8235527.11, "ymax": 4976491.56 },
  "center": { "lat": 40.7354, "lng": -73.99575 },
  "tile_indices": { "z": 15, "x": 9660, "y": 12284 },
  "epsg": "3857",
  "coord_order": "lng,lat",
  "area_km2": 8.681,
  "dimensions": { "width_km": 1.714, "height_km": 5.066 },
  "share_url": "https://vibhorsingh.com/boundingbox/#40.712800,-74.006000,40.758000,-73.985500"
}

Error handling

All errors return isError: true with a descriptive message. Invalid coordinates, unknown EPSG codes, and oversized H3 requests all return clean errors — the server never crashes on bad input.

Logging

Structured JSON logs go to stderr (stdout is reserved for MCP protocol). Each entry includes timestamp, level, and context.

---

License

MIT