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: support@mapsi.dev

---

License

MIT — algolayer.com