mapsi-mcp

MCP server for Mapsi — 18 geospatial tools for AI coding assistants. Connect Claude Code, Cursor, Windsurf, or any MCP-compatible IDE directly to Mapsi APIs.

OpenStreetMap-based · Self-hosted infrastructure · No Google Maps vendor lock-in

Quick Start

1. Get your API key at mapsi.dev/console/api-keys (free tier: 1,000 calls/day, no credit card)

2. Add the config to your IDE:

Claude Code / Claude Desktop

Add to ~/.claude.json (or .mcp.json in your project root):

{
  "mcpServers": {
    "mapsi": {
      "command": "npx",
      "args": ["-y", "mapsi-mcp"],
      "env": { "MAPSI_API_KEY": "msk_your_key_here" }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mapsi": {
      "command": "npx",
      "args": ["-y", "mapsi-mcp"],
      "env": { "MAPSI_API_KEY": "msk_your_key_here" }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json — same JSON format as Cursor above.

VS Code + Cline

Open Cline settings → MCP Servers → Add server → paste:

{
  "mapsi": {
    "command": "npx",
    "args": ["-y", "mapsi-mcp"],
    "env": { "MAPSI_API_KEY": "msk_your_key_here" }
  }
}

Zed

Add to your Zed settings under "context_servers":

{
  "mapsi-mcp": {
    "command": { "path": "npx", "args": ["-y", "mapsi-mcp"] },
    "env": { "MAPSI_API_KEY": "msk_your_key_here" }
  }
}

3. Restart your IDE — then ask your AI in plain English.

What You Can Ask Your AI

Geocode all addresses in my CSV and add lat/lon columns
Build an address autocomplete input for this React form using Mapsi
Draw a 20-minute drive isochrone from our warehouse at this coordinate
Find the 5 nearest hospitals to this coordinate
Migrate this Google Maps geocoding call to Mapsi
Add a MapLibre map with Mapsi light tiles and drop markers from this array
Calculate a distance matrix between 10 warehouses and 50 delivery stops
Snap this GPS trace to the road network and calculate total distance

Available Tools (18)

Geocoding

| Tool | Description | |------|-------------| | geocode | Address or place name → lat/lon. Returns confidence score (0–1); treat scores below 0.6 as ambiguous. | | reverse_geocode | lat/lon → formatted address, street, city, postcode, country. | | autocomplete | Real-time address suggestions as user types (min 2 chars). For UI input fields. | | normalize_address | Standardize messy/inconsistent addresses. Returns structured fields + coordinates. | | timezone | IANA timezone name + UTC offset + DST status for any coordinate. | | elevation | Altitude in metres for any coordinate (~30m resolution globally). |

Routing

| Tool | Description | |------|-------------| | route | Turn-by-turn directions. Modes: auto, truck, bicycle, pedestrian, motor_scooter. | | isochrone | Reachability polygon within N minutes or N metres. Returns GeoJSON for MapLibre/Leaflet. | | matrix | Travel time + distance matrix for up to 50×50 origin-destination pairs in one call. | | map_match | Snap a GPS trace to the road network. Coordinates are [lon, lat] order (GeoJSON). | | nearest_road | Find nearest routable road point. Call this if route returns "no route found". |

Places

| Tool | Description | |------|-------------| | places_search | Find nearby POIs by category (restaurant, hospital, pharmacy, ATM…). Returns name, coords, categories. |

Spatial

| Tool | Description | |------|-------------| | point_in_polygon | Admin hierarchy for a coordinate: country, region, city, neighbourhood. | | h3_index | Convert coordinate to H3 hexagonal grid cell at resolution 0–15. |

Batch

| Tool | Description | |------|-------------| | batch_geocode | Geocode up to 30,000 addresses in a single call. Never loop geocode for bulk data. | | batch_reverse_geocode | Reverse geocode multiple coordinates in one call. |

Tiles

| Tool | Description | |------|-------------| | get_tile_style_url | MapLibre GL style URL. Styles: light, dark, streets, topo, grayscale, black, white, liberty. | | get_static_map_url | Static PNG map URL for use in <img> tags, emails, and PDFs. |

Auth

• API calls: X-API-Key header (handled automatically by the MCP server)
• Tile URLs: ?key= query param (browser-safe; returned by get_tile_style_url)

Common Patterns for Agents

Geocode once, reuse the result:

Don't re-geocode the same address twice within a session. Cache the lat/lon and pass it directly to route, isochrone, and places_search.

Bulk data → batch tools:

For more than 1 address or coordinate pair, always use batch_geocode / batch_reverse_geocode.

Route fails → nearest_road first:

If route returns an error near the origin or destination, call nearest_road to snap the point to a routable road, then retry route with the snapped coordinates.

Isochrone — time vs distance:

Use contours_minutes for time-based reachability (delivery ETAs, commute zones).
Use contours_meters for fixed-radius circles on the road network.
Provide only one, not both.

Pricing

| Plan | Calls/day | Batch size | |------|-----------|------------| | Free | 1,000 | 10 | | Growth | 50,000 | 5,000 | | Business | Unlimited | 30,000 |

Full pricing at mapsi.dev/pricing

Links

• Website: mapsi.dev
• API docs: mapsi.dev/docs
• AI prompts: mapsi.dev/prompts-for-ai
• npm: npmjs.com/package/mapsi-mcp
• GitHub: github.com/algolayer/mapsi-mcp
• Support: [email protected]

License

MIT — algolayer.com