🌍 bbox-mcp-server
Ask AI about anything, anywhere — and verify the answer on a map. For Free
The geospatial toolkit for AI agents. 6 tools, zero config — give any LLM the ability to find, query, convert, and aggregate spatial data using open data. No API keys or signups required to start.
Every response includes a shareable verification link to vibhorsingh.com/boundingbox — click it to visually confirm results on an interactive map. No other MCP server does this.
What Can You Do With This?
You don't have to be a GIS professional to make use of this. Any AI agent with this MCP server can answer spatial questions using real OpenStreetMap data and not spit out hallucinated garbage.
| Ask your AI agent... | What happens under the hood |
|---|
| "How many EV chargers are in downtown Denver?" | Overpass query → H3 hex binning → density analysis |
| "Is there a hospital near this Airbnb?" | POI search with structured tags → map verification link |
| "Find all playgrounds within 1km of this address"* | Overpass query + radius filter → pinned results on a shareable map |
| "Convert this WKT to GeoJSON in EPSG:3857" | Format conversion across 6 inputs, 9 outputs, 3,900+ projections |
| "Show me all bike-share stations in Amsterdam" | Curated OSM tags → Overpass query → results on map |
| "Compare park density across Seattle neighborhoods" | Overpass + H3 aggregation → hex-binned spatial analysis |
Every answer comes with a link. Click it, see if the AI got it right and you can also share it with someone else.
What Makes This Different
Most AI tools give you text you have to trust. This one gives you an interactive map you can check and verify!
- Verifiable — Every response includes a public URL where you (or anyone) can visually confirm the results. This is the only MCP server that does this in any domain.
- Deterministic — Queries hit real OpenStreetMap data and return real coordinates. The AI interprets your question. The data comes from all the hard work done by all the awesome OSM volunteers.
- Free — No paid services. Overpass API is free, OSM data is free, the tool is free. A Mapbox token (free tier, no payment info) unlocks natural language location search but isn't required.
- Zero config —
npx -y bbox-mcp-server and you're running.
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. |
| 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 within a bbox or radius | bbox, query, limit, radius_meters |
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:
Claude Desktop (Click to expand)
Add to claude_desktop_config.json:
{
"mcpServers": {
"bbox": {
"command": "npx",
"args": ["-y", "bbox-mcp-server"]
}
}
}
Cursor (Click to expand)
Add to .cursor/mcp.json:
{
"mcpServers": {
"bbox": {
"command": "npx",
"args": ["-y", "bbox-mcp-server"]
}
}
}
Windsurf (Click to expand)
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"bbox": {
"command": "npx",
"args": ["-y", "bbox-mcp-server"]
}
}
}
VS Code (GitHub Copilot) or Google Antigravity (Click to expand)
Add to .vscode/mcp.json in your workspace:
{
"servers": {
"bbox": {
"command": "npx",
"args": ["-y", "bbox-mcp-server"]
}
}
}
Try: "Find all coffee shops within 500m of Times Square"
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",
"NOMINATIM_API_URL": "https://your.custom.nominatim.instance"
}
}
}
}
| 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. |
NOMINATIM_API_URL | https://nominatim.openstreetmap.org | Custom Nominatim endpoint. Set this if hosting as a shared/remote MCP server or using a commercial provider. |
MAX_H3_CELLS | 50000 | Safety cap for H3 grid generation |
Or install globally: npm install -g bbox-mcp-server
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 query within a bounding box or radius. Returns structured results with names, coordinates, and tags. The verification link plots each result as a pin on the map.
| Param | Type | Default | Description |
|---|
bbox | string | — | Input geometry |
query | string | — | Overpass QL (e.g. nwr["amenity"="cafe"]). The server wraps it in the appropriate spatial filter automatically. |
radius_meters | number | — | Search radius in metres. Use only when the user specifies an explicit distance (e.g. 2000 for "within 2km"). Omit for area/region queries. |
limit | number | 100 | Max elements returned |
💡 Prompt: "Find all parking within 2km of JFK airport"
💡 Prompt: "Search for hospitals in Manhattan, limit 50"
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"
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.
Acknowledgments & Fair Use
OpenStreetMap
This tool is built on OpenStreetMap: A global dataset created and maintained by millions of volunteers. Every query you run returns data that someone walked, mapped, or verified by hand. If you find this useful, consider contributing to OSM.
Responsible Usage
The public Overpass and Nominatim API instances are free community resources with limited capacity. Avoid tight loops, excessive polling, or bulk-scraping. If hosting this as a shared/remote MCP server, point NOMINATIM_API_URL and OVERPASS_API_URL at your own instance or a commercial provider (see Overpass API installation and Nominatim installation). The default server rotation for Overpass helps spread load, but it's not a substitute for responsible usage.
License
MIT
