🌍 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.

Node.js License: MIT MCP Badge

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:

Human-readable text — formatted output with the map verification link
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

bbox-mcp-server